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NAME 

intro  —  introduction  to  commands 
DESCRIPTION 

This  section  describes  publicly  accessible  commands  in  alphabetic  order.  Certain  distinctions  of 
purpose  are  made  in  the  headings: 

(1)  Commands  of  general  utility. 

(1C)  Commands  for  communication  with  other  systems. 

(IG)  Commands  used  primarily  for  graphics  and  computer-aided  design. 

SEE  ALSO 

•  Section  6  in  this  manual  for  computer  games. 

•  Section  7  in  this  manual  for  descriptions  of  publicly  available  files  and  macro  packages  for 
document  preparation. 

•  Section  8  in  this  manual  for  system  administration  procedures,  system  maintenance  and  opera¬ 
tion  commands,  plus  descriptions  of  network  services  daemons  and  servers. 

•  Getting  Started  in  the  Beginner’s  Guide  to  the  Sun  Workstation. 

DIAGNOSTICS 

Upon  termination  each  command  returns  two  bytes  of  status,  one  supplied  by  the  system  giving 
the  cause  for  termination,  and  (in  the  case  of  ‘normal’  termination)  one  supplied  by  the  program, 
see  wait  and  exit(2).  The  former  byte  is  0  for  normal  termination,  the  latter  is  customarily  0  for 
successful  execution,  nonzero  to  indicate  troubles  such  as  erroneous  parameters,  bad  or  inaccessi¬ 
ble  data,  or  other  inability  to  cope  with  the  task  at  hand.  It  is  called  variously  ‘exit  code’,  ‘exit 
status’  or  ‘return  code’,  and  is  described  only  where  special  conventions  are  involved. 


Sun  Release  2.0 


Last  change:  6  April  1985 


1 


ADB(l) 


USER  COMMANDS 


ADB(l) 


NAME 

adb  —  debugger 
SYNOPSIS 

adb  I  — w  ]  I  — k  j  (  — Idir  |  [  objfil  [  corfil  ]  ] 

DESCRIPTION 

Adh  is  an  interactive,  general  purpose  debugger*  It  examines  files  and  provides  a  controlled 
environment  for  the  execution  of  UNIX  programs. 

Objfil  is  normally  an  executable  program  file,  preferably  containing  a  symbol  table.  If  the  file  does 
not  contain  a  symbol  table,  it  can  still  be  examined,  but  the  symbolic  features  of  adh  cannot  be 
used.  The  default  for  objfil  is  a*out.  Corfil  is  assumed  to  be  a  core  image  file  produced  after 
executing  objfiL  The  default  for  corfil  is  core* 

OPTIONS 

— w  Create  both  objfil  and  corfil  if  necessary  and  open  them  for  reading  and  writing  so  that 

files  can  be  modified  using  adb, 

— k  Do  UNIX  kernel  memory  mapping;  should  be  used  when  core  is  a  UNIX  crash  dump  or 

/dev/mem. 

—1  specifies  a  directory  where  files  to  be  read  with  $<  or  $«  (see  below)  will  be  sought; 
the  default  is  /usr/lib/adb, 

USING  ADB 

Adb  reads  commands  from  the  standard  input  and  displays  responses  on  the  standard  output. 
Adb  ignores  QUIT;  INTERRUPT  causes  return  to  the  next  adb  command. 

Adb  saves  and  restores  terminal  characteristics  when  running  a  sub— process.  This  makes  it  possi¬ 
ble  to  debug  programs  that  manipulate  the  screen.  See 

In  general,  requests  to  adb  are  of  the  form 

\addrese\  [,  count]  [command]  [;] 

The  symbol  dot  (*)  represents  the  current  location.  It  is  initially  zero.  If  address  is  present  then 
dot  is  set  to  address.  For  most  commands  count  specifies  how  many  times  the  command  will  be 
executed.  The  default  count  is  1.  Address  and  count  are  expressions. 

EXPRESSIONS 

•  The  value  of  dot, 

+  The  value  of  dot  incremented  by  the  current  increment. 

The  value  of  dot  decremented  by  the  current  increment. 

&  The  last  address  typed.  (Used  to  be 

integer  A  number.  The  prefixes  Oo  and  OO  (‘‘zero  oh”)  force  interpretation  in  octal  radix;  the 
prefixes  Ot  and  OT  force  interpretation  in  decimal  radix;  the  prefixes  Ox  and  OX  force 
interpretation  in  hexadecimal  radix.  Thus  0o20  ==»  0tl6  —  0x10  =  sixteen.  If  no  prefix 
appears,  then  the  default  radix  is  used;  see  the  $d  command.  -The  default  radix  is  ini¬ 
tially  hexadecimal.  The  hexadecimal  digits  are  0123456789abcdcfABCDEF  with  the 
obvious  values.  Note  that  if  a  hexadecimal  number  starts  with  a  letter,  but  does  not 
duplicate  a  defined  symbol,  it  is  accepted  as  a  hexadecimal  value.  To  enter  a  hexade¬ 
cimal  number  that  is  the  same  as  a  defined  symbol,  preceed  it  by  0,  Ox,  or  OX. 

integer*fraction 

A  32  bit  floating  point  number. 

'cccc  "  The  ASCII  value  of  up  to  4  characters.  A  backslash  (‘\')  may  be  used  to  escape  a 
<  name 

The  value  of  name,  which  is  either  a  variable  name  or  a  register  name.  Adb  maintains  a 
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number  of  variables  (see  VARIABLES)  named  by  single  letters  or  digits.  If  name  is  a 
register  name  then  the  value  of  the  register  is  obtained  from  the  system  header  in  corfil. 
The  register  names  are  those  printed  by  the  $r  command, 

symbol  A  symbol  is  a  sequence  of  upper  or  lower  case  letters,  underscores  or  digits,  not  starting 
with  a  digit.  The  backslash  character  \  may  be  used  to  escape  other  characters.  The 
value  of  the  symbol  is  taken  from  the  symbol  table  in  objfiL  An  initial  _  will  be 
prepended  to  symbol  if  needed. 

_  symbol 

In  C,  the  ‘true  name’  of  an  external  symbol  begins  with  ‘J.  It  may  be  necessary  to  use 
this  name  to  distinguish  it  from  internal  or  hidden  variables  of  a  program. 

routine. name 

The  address  of  the  variable  name  in  the  specified  C  routine.  Both  routine  and  name  are 
symbols.  If  name  is  omitted  the  value  is  the  address  of  the  most  recently  activated  C 
stack  frame  corresponding  to  routine. 

(exp  )  The  value  of  the  expression  exp. 

Unary  operators 

^exp  The  contents  of  the  location  addressed  by  exp  in  corfil. 

%exp  The  contents  of  the  location  addressed  by  exp  in  objfil.  (Used  to  be  @.) 

—exp  Integer  negation. 

^exp  Bitwise  complement. 

#ea:p  Logical  negation. 

"Fexp  (Control— f)  Translates  program  addresses  into  sourcefile  addresses, 

program  has  been  compiled  using  the  —go  flag.  See  cc(l).) 

^Aexp  (Control— a)  Translates  sourcefile  addresses  into  program  addresses, 
program  has  been  compiled  using  the  —go  flag.  See  cc(l).) 

'  name  (Back— quote)  Translates  a  procedure  name  into  a  sourcefile  address, 
program  has  been  compiled  using  the  —go  flag.  See  cc(l).) 

^'filename'' 

A  filename  enclosed  in  quotation  marks  (for  instance,  ”main.c**)  produces  the  sourcefile 
address  for  the  zero-th  line  of  that  file.  Thus  to  reference  the  third  line  of  the  file 

main.c,  we  say:  ’’main.c**-|-3.  (Works  only  if  the  program  has  been  compiled  using  the 

—go  flag.  See  cc(l).) 

Binary  operators  are  left  associative  and  are  less  binding  than  unary  operators. 

el-\-eS  Integer  addition. 

el  —  e2  Integer  subtraction. 

el^e2  Integer  multiplication. 

el%e2  Integer  division. 

el&e2  Bitwise  conjunction. 

el  \e2  Bitwise  disjunction. 

elif^e2  El  rounded  up  to  the  next  multiple  of  e2. 

VARIABLES 

Adb  provides  a  number  of  variables.  Named  variables  are  set  initially  by  adb  but  are  not  used 
subsequently.  Numbered  variables  are  reserved  for  communication  as  follows. 

0  The  last  value  printed. 


(Works  only  if  the 
(Works  only  if  the 
(Works  only  if  the 
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1  The  last  offset  part  of  an  Instruction  source. 

2  The  previous  value  of  variable  1. 

9  The  count  on  the  last  $<  or  $«  command. 

On  entry  the  following  are  set  from  the  system  header  in  the  corfil.  If  corfil  does  not  appear  to 
be  a  core  file  then  these  values  are  set  from  objfiL 

b  The  base  address  of  the  data  segment, 

d  The  data  segment  size, 

e  The  entry  point. 

m  The  ‘magic'  number  (0407,  0410  or  0413). 
s  The  stack  segment  size, 

t  The  text  segment  size. 

COMMANDS 

Adb  commands  consist  of  a  verb  followed  by  a  modifier  or  list  of  modifiers. 

The  verbs  are: 

?  Print  locations  starting  at  addrtdd  in  objfii. 

f  Print  locations  starting  at  address  in  corfil. 

—  Print  the  value  of  address  itself. 

@  Interpret  address  as  a  sourcefile  address,  and  print  locations  in  objfile  or  lines  of  the 
source  text.  (Works  only  if  the  program  has  been  compiled  using  the  —go  flag.  See 

CC{1).) 

X  Manage  a  subprocess, 

t  Execute  miscellaneous  commands. 

>  Assign  a  value  to  a  variable  or  register. 

RETURN 

Repeat  the  previous  command  with  a  count  of  1.  Dot  is  incremented  by  its  current  incre¬ 
ment. 

!  Call  the  shell  to  execute  the  following  command. 

Each  verb  has  a  specific  set  of  modifiers,  these  are  described  below, 

[  7)  /»  @»  =  ]  Modifiers 

The  first  four  verbs  described  above  take  the  same  set  of  modifiers.  These  modifiers  specify  the 
format  of  command  output.  Each  modifier  consists  of  a  letter  preceded  by  an  optional  repeat 
count;  each  verb  may  take  one  or  more  modifiers: 

I  7,  —  I  [  1  rcount  j  fietter  •••  ] 

Each  time  one  of  these  commands  is  given,  dot  is  incremented  by  a  certain  amount  (sum  of  the 
increments  specific  to  each  format  letter,  see  below).  If  a  command  is  given  without  a  modifier, 
the  last  specified  format  is  used  to  display  output.  The  following  lists  the  format  letter,  the 
amount  dot  increments  each  time  the  letter  is  used,  and  a  description  of  what  each  letter  does, 
o  2  Print  2  bytes  in  octal.  All  octal  numbers  output  by  adb  are  preceded  by  0. 

O  4  Print  4  bytes  in  octal, 

q  2  Print  in  signed  octal. 

Q  4  Print  long  signed  octal, 

d  2  Print  in  decimal. 

D  4  Print  long  decimal. 
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X  2  Print  2  bytes  in  hexadecimal. 

X  4  Print  4  bytes  in  hexadecimal, 

u  2  Print  as  an  unsigned  decimal  number. 

U  4  Print  long  unsigned  decimal, 

f  4  Print  the  32  bit  value  as  a  floating  point  number. 

F  8  Print  double  floating  point, 

b  1  Print  the  addressed  byte  in  octal, 

c  1  Print  the  addressed  character, 

C  1  Print  the  addressed  character  using  the  standard  escape  convention:  print  control 
characters  as  "X  and  the  delete  character  as  "?. 

0  n  Print  the  addressed  characters  until  a  zero  character  is  reached. 

S  n  Print  a  string  using  the  "X  escape  convention  (see  C  above),  n  is  the  length  of  the 

string  including  its  zero  terminator. 

Y  4  Print  4  bytes  in  date  format  (see  c^tme(3)). 

I  n  Print  as  machine  instructions,  n  is  the  number  of  bytes  occupied  by  the  instruction. 

In  this  format,  variables  1  and  2  are  set  to  the  offset  parts  of  the  source  and  destina¬ 
tion  respectively. 

0  n  Print  as  machine  instructions  with  68010  instruction  timings,  n  is  the  number  of 

bytes  occupied  by  the  instruction.  In  this  format,  variables  1  and  2  are  set  to  the 
offset  parts  of  the  source  and  destination  respectively. 

I  0  Print  the  source  text  line  specified  by  dot  (@  command)  or  most  closely  correspond¬ 

ing  to  dot  (?  command). 

a  0  Print  the  value  of  dot  in  symbolic  form.  Symbols  are  checked  to  ensure  that  they 
have  an  appropriate  type  as  indicated  below. 

/  local  or  global  data  symbol 

?  local  or  global  text  symbol 

»=*  local  or  global  absolute  symbol 

p  4  Print  the  addressed  value  in  symbolic  form  using  the  same  rules  for  symbol  lookup  as 

a. 

A  0  Print  the  value  of  dot  in  sourcefile  symbolic  form,  that  is:  **yi/enflme"+nnn.  (Works 
only  if  the  program  has  been  compiled  using  the  —go  flag.  See  cc(l).) 

P  4  Print  the  addressed  value  in  sourcefile  symbolic  form,  that  is:  ^ filename^ -i-nnn, 
(Works  only  if  the  program  has  been  compiled  using  the  —go  flag.  See  cc(l).) 
t  0  When  preceded  by  an  integer,  tabs  to  the  next  appropriate  tab  stop.  For  example, 
8t  moves  to  the  next  8-space  tab  stop, 
r  0  Print  a  space, 

n  0  Print  a  newline. 

Print  the  enclosed  string. 

Dot  is  decremented  by  the  current  increment.  Nothing  is  printed. 

-h  Dot  is  incremented  by  1.  Nothing  is  printed. 

—  Dot  is  decremented  by  1.  Nothing  is  printed. 


[  r,  /]  Modmers 

[r/|I  value  mask 

Words  starting  at  dot  are  masked  with  mask  and  compared  with  value  until  a  match 
is  found.  If  L  is  used  then  the  match  is  for  4  bytes  at  a  time  instead  of  2.  If  no 
match  is  found  then  dot  is  unchanged;  otherwise  dot  is  set  to  the  matched  location. 
If  mask  is  omitted  then  —1  is  used. 

[r/]w  value  ... 
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Write  the  2-byte  value  into  the  addressed  location.  If  the  command  is  W,  write  4 
bytes.  Odd  addresses  are  not  allowed  when  writing  to  the  subprocess  address  space. 
[r/|m  bl  el  /i|f/j 

New  values  for  {bl,  el,  fl)  are  recorded.  If  less  than  three  expressions  are  given  then 
the  remaining  map  parameters  are  left  unchanged.  If  the  T  or  7*  is  followed  by  V* 
then  the  second  segment  {b2,  e2,f2)  of  the  address  mapping  is  changed  (see  ADDRESS 
MAPPING,  below).  If  the  list  is  terminated  by  'V  or  7’  then  the  file  [objfil  or  corfil 
respectively)  is  used  for  subsequent  requests.  (So  that,  for  example,  7^-’  will  cause 
7’  to  refer  to  objfiL) 


t  ModIfierB 

be  Set  breakpoint  at  address.  The  breakpoint  is  executed  count— I  times  before  causing 

a  stop.  Each  time  the  breakpoint  is  encountered  the  command  c  is  executed.  If  this 
command  is  omitted  or  sets  dot  to  zero  then  the  breakpoint  causes  a  stop. 

Be  Like  b  but  takes  a  sourcefile  address.  (Works  only  if  the  program  has  been  compiled 

using  the  —go  flag.  See  <^c(l).) 

d  Delete  breakpoint  at  address. 

D  Like  d  but  takes  a  sourcefile  address.  (Works  only  if  the  program  has  been  compiled 

using  the  —go  flag.  See  <?<^(l).) 

r  Run  objfil  as  a  subprocess.  If  address  is  given  explicitly  then  the  program  is  entered 

at  this  point;  otherwise  the  program  is  entered  at  its  standard  entry  point,  count 
specifies  how  many  breakpoints  are  to  be  ignored  before  stopping.  Arguments  to  the 
subprocess  may  be  supplied  on  the  same  line  as  the  command.  An  argument  starting 
with  <  or  >  causes  the  standard  input  or  output  to  be  established  for  the  command. 
All  signals  are  enabled  on  entry  to  the  subprocess. 

The  subprocess  is  continued  with  signal  a,  see  stgvec{2).  If  address  is  given  then  the 
subprocess  is  continued  at  this  address.  If  no  signal  is  specified  then  the  signal  that 
caused  the  subprocess  to  stop  is  sent.  Breakpoint  skipping  is  the  same  as  for  r. 

Bs  As  for  c  except  that  the  subprocess  is  single  stepped  count  times.  If  there  is  no 

current  subprocess  then  objfil  is  run  as  a  subprocess  as  for  r.  In  this  case  no  signal 
can  be  sent;  the  remainder  of  the  line  is  treated  as  arguments  to  the  subprocess. 

S  Like  8  but  single  steps  source  lines,  rather  than  machine  instructions.  This  is 

acheived  by  repeatedly  single— stepping  machine  instructions  until  the  corresponding 
sourcefile  address  changes.  (Thus  procedure  calls  cause  stepping  to  stop.)  (Works 
only  if  the  program  has  been  compiled  using  the  —go  flag.  See  cc(l).) 

i  Add  the  signal  specified  by  address  to  the  list  of  signals  which  are  passed  directly  to 

the  subprocess  with  the  minimum  of  interference.  Normally,  adh  intercepts  all  sig¬ 
nals  destined  for  the  subprocess,  and  the  user  must  use  the  :c  command  to  continue 
the  process  with  the  signal.  Signals  on  this  list  are  handed  to  the  process  with  an 
implicit  :c^  as  soon  as  they  are  seen. 

t  Remove  the  signal  specified  by  address  from  the  list  of  signals  that  are  implicitly 

passed  to  the  subprocess. 

k  Terminate  the  current  subprocess,  if  any. 

%  ModiflerB 

<file  Read  commands  from  the  file  file.  If  this  command  is  executed  in  a  file,  further 

commands  in  the  file  are  not  seen.  If  file  is  omitted,  the  current  input  stream  is  ter¬ 
minated.  If  a  count  is  given,  and  is  zero,  the  command  will  be  ignored.  The  value  of 
the  count  will  be  placed  in  variable  9  before  the  first  command  in  file  is  executed. 

«file  Similar  to  <,  but  can  be  used  in  a  file  of  commands  without  closing  the  file.  Vari¬ 
able  9  is  saved  during  the  execution  of  this  command,  and  restored  when  it 
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completes.  There  is  a  (small)  finite  limit  to  the  number  of  «  files  that  can  be  open 
at  once. 

^file  Append  output  to  file,  which  is  created  if  it  does  not  exist.  If  file  is  omitted,  output 
is  returned  to  the  terminal. 

?  Print  process  id,  the  signal  which  stopped  the  subprocess,  and  the  registers.  Pro¬ 

duces  the  same  response  as  $  used  without  any  modifier, 
r  Print  the  genera!  registers  and  the  instruction  addressed  by  pc.  Dot  is  set  to  pc. 

b  Print  all  breakpoints  and  their  associated  counts  and  commands, 

c  C  stack  backtrace.  If  address  is  given  then  it  is  taken  as  the  address  of  the  current 

frame  instead  of  the  contents  of  the  frame— pointer  register.  If  count  is  given  then 

only  the  first  count  frames  are  printed. 

C  Similar  to  c,  but  in  addition  prints  the  names  and  (32  bit)  values  of  all  automatic 

and  static  variables  for  each  active  function.  (Works  only  if  the  program  has  been 
compiled  using  the  —go  flag.  See  cc(l).) 

d  Set  the  default  radix  to  address  and  report  the  new  value.  Note  that  address  is 

interpreted  in  the  (old)  current  radix.  Thus  *‘10$d”  never  changes  the  default  radix. 
To  make  decimal  the  default  radix,  use  ‘*OtlO$d”. 
e  Print  the  names  and  values  of  external  variables, 

w  Set  the  page  width  for  output  to  address  (default  80). 

s  Set  the  limit  for  symbol  matches  to  address  (default  255). 

o  All  integers  input  are  regarded  as  octal, 

q  Exit  from  adb, 

V  Print  all  non  zero  variables  in  octal, 

m  Print  the  address  map. 

f  Print  a  list  of  known  source  file  names, 

p  Print  a  list  of  known  procedure  names. 

p  {Kernel  debugging)  Change  the  current  kernel  memory  mapping  to  map  the  desig¬ 

nated  user  structure  to  the  address  given  by  the  symbol  The  address  argument 
is  the  address  of  the  user’s  proc  structure. 

i  Show  which  signals  are  passed  to  the  subprocess  with  the  minimum  of  adb  interfer¬ 

ence,  Signals  may  be  added  to  or  deleted  from  this  list  using  the  :i  and  :t  com¬ 
mands. 

W  Re-open  objfile  and  corfile  for  writing,  as  though  the  — w  command-line  argument 

had  been  given. 

ADDRESS  MAPPING 

The  interpretation  of  an  address  depends  on  the  context  it  is  used  in.  If  a  subprocess  is  being 
debugged,  addresses  are  interpreted  in  the  usual  way  (as  described  below)  in  the  address  space  of 
the  subprocess.  If  the  operating  system  is  being  debugged,  either  post-mortem  or  by  using  the 
special  file  /dev/mem  to  interactively  examine  and/or  modify  memory,  the  maps  are  set  to  map 
the  kernel  virtual  addresses  which  start  at  zero.  For  some  commands,  the  address  is  not  inter¬ 
preted  as  a  memory  address  at  all,  but  as  an  ordered  pair  representing  a  file  number  and  a  line 
number  within  that  file.  The  @  command  always  takes  such  a  sourcefile  address,  and  several 
operators  are  available  to  convert  to  and  from  the  more  customary  core  locations. 

The  address  in  a  file  associated  with  a  written  address  is  determined  by  a  mapping  associated 
with  that  file.  Each  mapping  is  represented  by  two  triples  [bl,  el,  fl)  and  {bS,  e2,  f2)  and  the 
file  address  corresponding  to  a  written  address  is  calculated  as  follows. 

blKaddressC^el  »>  file  address^address‘\'fl-’bl,  otherwise, 
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bS<addre8a<eS  «>  file  addre88**addre88+f2—b2, 

otherwise,  the  requested  addreaa  is  not  legal.  If  a  ?  or  /  is  followed  by  an  *  then  only  the  second 
triple  is  used. 

The  initial  setting  of  both  mappings  is  suitable  for  normal  a.out  and  core  files.  If  either  file  is 
not  of  the  kind  expected  then,  for  that  file,  bl  is  set  to  0,  el  is  set  to  the  maximum  file  size  and 
fl  is  set  to  0;  in  this  way  the  whole  file  can  be  examined  with  no  address  translation. 

FILES 

a.out 

core 

SEE  ALSO 

cc(l),  dbx(l),  ptrace(2),  a,out(5),  core(5) 

Uaing  adb  to  debug  the  UNIX  kernelin  the  Sun  System  Internals  Guide. 

DIAGNOSTICS 

*Adb’  when  there  is  no  current  command  or  format.  Comments  about  inaccessible  files,  syntax 
errors,  abnormal  termination  of  commands,  etc.  Exit  status  is  0,  unless  last  command  failed  or 
returned  nonzero  status. 

BUGS 

There  doesn’t  seem  to  be  any  way  to  clear  all  breakpoints. 

Adb  uses  the  symbolic  information  in  an  old  and  now  obsolete  format  generated  by  the  —go  flag 
of  cc(l):  it  should  be  changed  to  use  the  new  format  used  by  the  dbx  debugger  and  generated  by 

Since  no  shell  is  invoked  to  interpret  the  arguments  of  the  tr  command,  the  customary 
wild-card  and  variable  expansions  cannot  occur. 

Since  there  is  little  type— checking  on  addresses,  using  a  sourcefile  address  in  an  inappropriate 
context  may  lead  to  unexpected  results:  ‘mainfi  will  almost  certainly  not  do  anything  useful. 
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NAME 

addbib  —  create  or  extend  bibliographic  database 
SYNOPSIS 

addbib  |  — p  promptfile  j  [  — a  )  database 
DESCRIPTION 

When  this  program  starts  up,  answering  “y*’  to  the  initial  “Instructions?”  prompt  yields  direc¬ 
tions;  typing  “n”  or  RETURN  skips  them.  Addhih  then  prompts  for  various  bibliographic  fields, 
reads  responses  from  the  terminal,  and  sends  output  records  to  a  datahast.  A  null  response  (just 
return)  means  to  leave  out  that  field.  A  minus  sign  (— )  means  to  go  back  to  the  previous  field. 
A  trailing  backslash  allows  a  field  to  be  continued  on  the  next  line.  The  repeating  “Continue?” 
prompt  allows  the  user  either  to  resume  by  typing  “y”  or  RETURN,  to  quit  the  current  session  by 
typing  “n”  or  “q”,  or  to  edit  the  database  with  any  system  editor  (vi,  ex,  edit,  erf/ 

The  —a  option  suppresses  prompting  for  an  abstract;  asking  for  an  abstract  is  the  default. 
Abstracts  are  ended  with  a  CTRL-d.  The  — p  option  causes  addbib  to  use  a  new  prompting  skele¬ 
ton,  defined  in  promptfile.  This  file  should  contain  prompt  strings,  a  tab,  and  the  key-letters  to  be 
written  to  the  database. 

The  most  common  key-letters  and  their  meanings  are  given  below.  Addbib  insulates  you  from 
these  key-letters,  since  it  gives  you  prompts  in  English,  but  if  you  edit  the  bibliography  file  later 
on,  you  will  need  to  know  this  information. 

%A  Author’s  name 

%B  Book  containing  article  referenced 

%C  City  (place  of  publication) 

%D  Date  of  publication 

%E  Editor  of  book  containing  article  referenced 

%F  Footnote  number  or  label  (supplied  by  refer) 

%G  Government  order  number 

%H  Header  commentary,  printed  before  reference 

%l  Issuer  (publisher) 

%J  Journal  containing  article 

%K  Keywords  to  use  in  locating  reference 
%L  Label  field  used  by  — k  option  of  refer 
%M  Bel!  Labs  Memorandum  (undefined) 

%N  Number  within  volume 

%0  Other  commentary,  printed  at  end  of  reference 
%P  Page  number(s) 

%Q  Corporate  or  Foreign  Author  (unreversed) 

%R  Report,  paper,  or  thesis  (unpublished) 

%S  Series  title 

%T  Title  of  article  or  book 

%V  Volume  number 

%X  Abstract  —  used  by  roffbiby  not  by  refer 
%Y,Z  ignored  by  refer 


Except  for  ‘A’,  each  field  should  be  given  just  once.  Only  relevant  fields  should  be  supplied.  An 
example  is: 

%A  Bill  Tuthill 

%T  Refer  —  A  Bibliography  System 

%\  Computing  Services 

%C  Berkeley 

%D  1982 
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%0  UNX  4.3,5, 

FILES 

promptfile  optional  file  to  define  prompting 

SEE  ALSO 

refer(l),  sortbib(l),  roffbib(l),  indxbib(l) 
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NAME 

adjacentscreens  —  notify  the  window  driver  of  the  physical  relationships  of  screens 
SYNOPSIS 

adjacentscreens  [  — c  j  — -m  ]  center  screen  [  [  — 1  j  — r  j  —t  [  — b  |  side  screen]  [  —x  ] 
DESCRIPTION 

Adjacentscreens  tells  the  mouse  cursor  tracking  mechanism  of  the  window  driver  how  to  move 
between  screens  that  contain  windows.  Once  properly  notified  using  adjacentscreens ^  the  mouse 
cursor  slides  from  one  screen  to  another  when  the  user  moves  the  cursor  off  the  edge  of  a  screen. 

OPTIONS 

— c  center  screen 

The  center  screen  is  a  frame  buffer  device  name,  such  as  /dev/fb.  All  the  other  physical 
screen  positions  are  relative  to  this  reference  point.  The  — c  flag  (c  for  center)  is 
optional.  If  no  further  arguments  are  present  on  the  command  line,  center  screen  is  set 
to  have  no  neighbors. 

— m  center  screen 

The  — m  flag  (m  for  middle)  may  be  used  instead  of  — c. 

—1  side  screen 

The  side  screen  is  also  a  frame  buffer  device  name,  such  as  fdev/cgoneO.  The  —I  flag 
means  that  side  screen  is  to  the  /eft  of  center  screen.  Up  to  four  repetitions  of  “flag 
side  screen"'  may  be  specified  on  the  command  line  to  define  the  four  neighbors  of  center 
screen. 

—T  side  screen 

Like  —I,  but  means  that  side  screen  is  to  the  right  of  center  screen, 

— t  side  screen 

Like  —1,  but  means  that  side  screen  is  on  top  of  center  screen. 

— b  side  screen 

Like  —1,  but  means  that  side  screen  is  Aelow  center  screen. 

““X  Suppresses  the  normal  notification  to  a  side  screen  cursor  tracker  that  center  screen  is 
its  only  neighbor.  This  option  is  useful  if  you  have  a  large  number  of  screens  or  want 
strange  inter-window  cursor  movement. 

EXAMPLE 

A  common  configuration  would  be  two  screens,  a  monochrome  {/dev/fb)  and  a  color  screen 
{/dev/cgoneO).  Let  us  assume  that  the  user  has  set  up  an  instance  of  suntools  on  each  screen 
(the  window  systems  must  be  running  before  adjacentscreens  is  run).  He  would  notify  the  win¬ 
dow  driver  that  the  color  screen  was  to  the  right  of  the  monochrome  screen  by  running 

adjacentscreens  /dev/fb  -r  /dev/cgoneO”  in  a  Shelltool  (see  ^un/cc/^(l)).  This  sets  up  cursor 
tracking  so  that  the  cursor  slides  from  the  monochrome  screen  to  the  color  screen  when  the  cur¬ 
sor  moves  off  the  right  hand  side  of  the  monochrome  screen.  Similarly,  the  cursor  slides  from 
the  color  screen  to  the  monochrome  screen  when  the  cursor  moves  off  the  left  hand  side  of  the 
color  screen. 

FILES 

/usr/suntool/adjacentscreens 

SEE  ALSO 

suntools(l),  login(l) 

BUGS 

Window  systems  on  the  screens  have  to  be  initialized  before  running  adjacentscreens. 
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NAME 

admin  —  create  and  administer  SCCS  files 

SYNOPSIS 

/uBr/sccs/admln  I  -n  j  [  -I] name] |  ]  -rrel  ]  (  -t| name]]  [  -tfiag  \Jlag-val\] 

I  -d^a^f  [  /2a^*t;a/  II  •  •  •  [  -^login  ]  . . .  [  -elogin  ]  •  • .  [  -m  |  mrlist  ]  \ 

I  — y  [cammen^ll  |  — h  ]  [  — *  |  filename 

DESCRIPTION 

Admin  creates  new  SCCS  files  and  changes  parameters  of  existing  ones.  Options  and  SCCS  file 
names  may  appear  in  any  order  on  the  admin  command  line.  SCCS  file  names  must  begin  with 
the  characters  ‘s/.  A  named  file  is  created  if  it  doesn’t  exist  already,  and  its  parameters  are  ini¬ 
tialized  according  to  the  specified  options.  Any  parameter  not  initialized  by  an  option  is  assigned 
a  default  value.  If  a  named  file  does  exist,  parameters  corresponding  to  specified  options  are 
changed,  and  other  parameters  are  left  as  is. 

If  a  directory  is  named,  admin  behaves  as  though  each  file  in  the  directory  were  specified  as  a 
named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with  s.) 
and  unreadable  files  are  silently  ignored.  A  name  of  —  means  the  standard  input  —  each  line  of 
the  standard  input  is  taken  as  the  name  of  an  SCCS  file  to  be  processed.  Again,  non-SCCS  files 
and  unreadable  files  are  silently  ignored. 

OPTIONS 

Options  are  explained  as  though  only  one  named  file  is  to  be  processed,  since  options  apply 
independently  to  each  named  file. 

— n  A  new  SCCS  file  is  being  created, 

'—I  [name  I 

Initial  text:  the  file  name  contains  the  text  of  a  new  SCCS  file.  The  text  is  the  first  delta 
of  the  file  —  see  — r  option  for  delta  numbering  scheme.  If  name  is  omitted,  the  text  is 
obtained  from  the  standard  input.  Omitting  the  —1  option  altogether  creates  an  empty 
SCCS  file.  You  can  only  create  one  SCCS  file  with  an  admin  —1  command.  Creating 
more  than  one  SCCS  file  with  a  single  admin  command  requires  that  they  be  created 
empty,  in  which  case  the  —I  option  should  be  omitted.  Note  that  the  —1  option  implies 
the  — n  option. 

— r  rel  Initial  release:  the  release  into  which  the  initial  delta  is  inserted.  — r  may  be  used  only  if 
the  —I  option  is  also  used.  The  initial  delta  is  inserted  into  release  1  if  the  — r  option  is 
not  used.  The  level  of  the  initial  delta  is  always  1,  and  initial  deltas  are  named  1.1  by 
default. 

— t  (name| 

Descriptive  text:  The  file  name  contains  descriptive  text  for  the  SCCS  file.  The  descrip¬ 
tive  text  file  name  must  be  supplied  when  creating  a  new  SCCS  file  (either  or  both  — n 
and  —1  options)  and  the  — t  option  is  used.  In  the  case  of  existing  SCCS  files:  l)  a  — t 
option  without  a  file  name  removes  descriptive  text  (if  any)  currently  in  the  SCCS  file, 
and  2)  a  -t  option  with  a  file  name  replaces  the  descriptive  text  currently  in  the  SCCS 
file  with  any  text  in  the  named  file. 

—tflag  Set  flag:  specifies  a  fiag,  and,  possibly,  a  value  for  the  flag,  to  be  placed  in  the  SCCS  file. 
Several  — f  options  may  be  supplied  on  a  single  admin  command  line.  Flags  and  their 
values  appear  in  the  FLAGS  section  after  this  list  of  options. 

— d^aj  Delete  fiag  from  an  SCCS  file.  The  — d  option  may  be  specified  only  when  processing 
existing  SCCS  files.  Several  — d  options  may  be  supplied  on  a  single  admin  command. 
See  the  FLAGS  section  below. 

—1  list  Unlock  the  specified  list  of  releases.  See  the  — f  option  for  a  description  of  the  1  flag  and 
the  syntax  of  a  list. 
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—a  login 

Add  login  name,  or  numerical  UNDC  group  ID,  to  the  list  of  users  who  may  make  deltas 
(changes)  to  the  SCCS  file.  A  group  ID  is  equivalent  to  specifying  all  login  names  com¬ 
mon  to  that  group  ID.  Several  —a  options  may  appear  on  a  single  admin  command  line. 
As  many  logins,  or  numerical  group  IDs,  as  desired  may  be  on  the  list  simultaneously.  If 
the  list  of  users  is  empty,  anyone  may  add  deltas. 

— e  login 

Erase  login  name,  or  numerical  group  ID,  from  the  list  of  users  allowed  to  make  deltas 
(changes)  to  the  SCCS  file.  Specifying  a  group  ID  is  equivalent  to  specifying  all  login 
names  common  to  that  group  ID.  Several  — e  options  may  be  used  on  a  single  admin 
command  line. 

—y  [comment] 

The  comment  text  is  inserted  into  the  SCCS  file  as  a  comment  for  the  initial  delta  in  a 
manner  identical  to  that  of  delta{l).  If  the  — y  option  is  omitted,  a  default  comment  line 
is  inserted  in  the  form: 

date  and  time  created  YY/MM/DD  HH:MM:SS  by  login 

The  — y  option  is  valid  only  if  the  —1  and/or  — n  options  are  specified  (that  is,  a  new 
SCCS  file  is  being  created). 

— m  (  mrlist  | 

The  list  of  Modification  Requests  (Affi)  numbers  is  inserted  into  the  SCCS  file  as  the  rea¬ 
son  for  creating  the  initial  delta  in  a  manner  identical  to  delta{l).  The  v  flag  must  be  set 
and  the  MR  numbers  are  validated  if  the  v  flag  has  a  value  (the  name  of  an  MR  number 
validation  program).  Diagnostics  are  displayed  if  the  v  flag  is  not  set  or  MR  validation 
fails. 

-h  Check  the  structure  of  the  SCCS  file  (sec  accBfile{5]),  and  compare  a  newly  computed 
check-sum  (the  sum  of  all  the  characters  in  the  SCCS  file  except  those  in  the  first  line) 
with  the  check-sum  that  is  stored  in  the  first  line  of  the  SCCS  file. 

The  — h  option  inhibits  writing  on  the  file,  so  that  it  nullifies  the  effect  of  any  other 
options  supplied,  and  is,  therefore,  only  meaningful  when  processing  existing  files. 

— *  recompute  the  SCCS  file  check-sum  and  store  it  in  the  first  line  of  the  SCCS  file  (see  — h, 

above). 

Using  the  — *  option  on  a  truly  corrupted  file  may  prevent  future  detection  of  the  corr¬ 
uption. 

FLAGS 

The  list  below  is  a  description  of  the  flags  which  may  appear  as  arguments  to  the  — f  (set  flags) 
and  — d  (delete  flags)  options. 

b  When  set,  the  — b  option  can  be  used  on  a  get{\)  command  to  create  branch  deltas. 

c  ceil  The  highest  release  (ceiling)  which  may  be  retrieved  by  a  get(l)  command  for  editing. 

The  ceiling  is  a  number  less  than  or  equal  to  9999.  The  default  value  for  an  unspecified 

c  flag  is  9999. 

f  floor  The  lowest  release  (floor)  which  may  be  retrieved  by  a  yel(l)  command  for  editing.  The 
floor  is  a  number  greater  than  0  but  less  than  9999.  The  default  value  for  an  unspecified 
f  flag  is  1. 

dS/D  The  default  delta  number  (SID)  to  be  used  by  a  je<(l)  command. 

i  Treats  the  ‘No  id  keywords  (gefl)’  message  issued  by  je<(l)  or  delta(l)  as  a  fatal  error. 

In  the  absence  of  the  i  flag,  the  message  is  only  a  warning.  The  message  is  displayed  if 

no  SCCS  identification  keywords  (see  get(l))  arc  found  in  the  text  retrieved  or  stored  in 
the  SCCS  file. 
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J  Concurrent  ffet{l)  commands  for  editing  may  apply  to  the  same  SID  of  an  SCCS  file. 

This  allows  multiple  concurrent  updates  to  the  same  version  of  the  SCCS  file. 

I  list  A  list  of  locked  releases  to  which  deltas  can  no  longer  be  made.  A  get  — «  fails  when 
applied  against  one  of  these  locked  releases.  The  list  has  the  following  syntax: 

<list> 

<range>  RELEASE  NUMBER  I  a 

The  character  a  in  the  list  is  equivalent  to  specifying  all  releases  for  the  named  SCCS  file. 

n  The  delta{l)  command  creates  a  ‘null’  delta  in  each  release  (if  any)  being  skipped  when  a 
delta  is  made  in  a  new  release.  For  example,  releases  3  and  4  are  skipped  when  making 
delta  5.1  after  delta  2.7.  These  null  deltas  serve  as  ‘anchor  points’  so  that  branch  deltas 
may  be  created  from  them  later.  If  the  n  flag  is  absent  from  the  SCCS  file,  skipped 
releases  will  be  non-existent  in  the  SCCS  file,  preventing  branch  deltas  from  being  created 
from  them  in  the  future. 

qtext  Text  is  defined  by  the  user.  The  text  is  substituted  for  all  occurrences  of  the  %Q%  key¬ 
word  in  SCCS  file  text  retrieved  by  iiel(l). 

m  module 

Module  name  of  the  SCCS  file  substituted  for  all  occurrences  of  the  %M%  keyword  in 
SCCS  file  text  retrieved  by  get[l).  If  the  m  flag  is  not  specified,  the  value  assigned  is  the 
name  of  the  SCCS  file  with  the  leading  b«  removed. 

ttype  Type  of  module  in  the  SCCS  file  substituted  for  all  occurrences  of  %Y%  keyword  in 
SCCS  file  text  retrieved  by  get{\). 

V I  program] 

Validity  checking  program:  delta{l)  prompts  for  Modification  Request  (MR)  numbers  as 
the  reason  for  creating  a  delta.  The  optional  program  specifies  the  name  of  an  MR 
number  validity  checking  program  (see  delta{l)).  If  this  flag  is  set  when  creating  an 
SCCS  file,  the  — m  option  must  also  be  used  even  if  its  value  is  null. 

FILES 

The  last  component  of  all  SCCS  file  names  must  be  of  the  form  ».file-name.  New  SCCS  files  are 
given  mode  444  (see  cAmorf(l)).  Write  permission  in  the  pertinent  directory  is,  of  course, 
required  to  create  a  file.  All  writing  done  by  admin  is  to  a  temporary  x-file,  called  x.file-name, 
(see  get{l)),  created  with  mode  444  if  the  admin  command  is  creating  a  new  SCCS  file,  or  with 
the  same  mode  as  the  SCCS  file  if  it  exists.  After  successful  execution  of  admin,  the  SCCS  file  is 
removed  (if  it  exists),  and  the  x-file  is  renamed  with  the  name  of  the  SCCS  file.  This  ensures  that 
changes  are  made  to  the  SCCS  file  only  if  no  errors  occurred. 

It  is  recommended  that  directories  containing  SCCS  files  be  mode  755  and  that  SCCS  files  them¬ 
selves  be  mode  444.  The  mode  of  the  directories  allows  only  the  owner  to  modify  SCCS  files  con¬ 
tained  in  the  directories.  The  mode  of  the  SCCS  files  prevents  any  modification  at  all  except  by 
SCCS  commands. 

If  it  should  be  necessary  to  patch  an  SCCS  file  for  any  reason,  the  mode  may  be  changed  to  644 
by  the  owner  allowing  use  of  a  text  editor.  ”Care  must  be  taken!”  The  edited  file  should  always 
be  processed  by  an  admin  — h  to  check  for  corruption  followed  by  an  admin  — *  to  generate  a 
proper  check-sum.  Another  admin  — h  is  recommended  to  ensure  the  SCCS  file  is  valid. 

Admin  also  uses  a  transient  lock  file  (called  t.file'name),  to  prevent  simultaneous  updates  to  the 
SCCS  file  by  different  users.  See  jel(l)  for  further  information. 

SEE  ALSO 

sccs(l),  delta(l),  ed(l),  get(l),  help(l),  prs(l),  what(l),  sccsfile(5). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 
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DIAGNOSTICS 

Use  Ae/p(l)  for  explanations. 
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NAME 

ar  -  archive  and  library  maintainer 
SYNOPSIS 

ar  djmjp[q{r[tjx  j  abcllouv  |  [  poename  ]  afile  name 
DESCRIPTION 

Ar  maintains  groups  of  files  combined  into  a  single  archive/library  file.  It  is  normally  used  to 
create  and  update  library  files  used  by  the  loader;  it  can  be  used,  though,  for  any  similar  pur¬ 
pose. 

One  of  the  mandatory  keys  (dmpqrtx)  must  be  used;  it  may  be  followed  by  one  or  more  of  the 
modifiers  abcllouv.  Afile  is  the  archive  file.  The  named  are  constituent  files  in  the  archive  file. 


OPTIONS 

d 

m 

P 

q 


r 

t 

X 

MODIFIERS 

a 

b 

c 

1 

I 

o 

u 

V 


Delete  the  named  files  from  the  archive  file. 

Move  the  named  files  to  the  end  of  the  archive. 

Display  the  named  files  in  the  archive. 

Quick  append.  Append  the  named  files  to  the  end  of  the  archive  file  without  searching 
the  archive  for  duplicate  names.  Useful  only  to  avoid  quadratic  behavior  when  creating 
a  large  archive  piece-by- piece. 

Replace  the  named  files  in  the  archive  file. 

Display  a  table  of  contents  of  the  archive  file.  If  no  names  are  given,  all  files  in  the 
archive  are  listed;  if  names  are  given,  only  those  files  are  listed. 

Extract  the  named  files.  If  no  names  are  given,  all  files  in  the  archive  are  extracted.  In 
neither  case  does  x  alter  the  archive  file. 


Place  new  files  after  posname  {posname  argument  must  be  present).  Applies  only  with 
the  r  and  m  options. 

Place  new  files  before  posname  {posname  argument  must  be  present).  Applies  only  with 
the  r  and  m  options. 

Ar  creates  afile  when  it  needs  to,  and  displays  a  message  to  this  effect.  The  c  modifier 
suppresses  this  message. 

Identical  to  the  b  modifier. 

Local.  Ar  places  its  temporary  files  in  the  directory  /tmp.  The  1  modifier  places  them  in 
the  local  directory. 

Old  date.  When  files  are  extracted  with  the  x  option,  o  sets  the  “last  modified”  date  to 
the  date  recorded  in  the  archive. 

Replace  only  those  files  that  have  changed  since  they  were  put  in  the  archive.  Used  with 
the  r  option. 

Verbose.  Give  a  file-by-fi!e  description  of  the  creation  of  a  new  archive  file  from  the  old 
archive  and  the  constituent  files.  When  used  with  t,  it  gives  a  long  listing  of  all  informa¬ 
tion  about  the  files.  When  used  with  p,  it  precedes  each  file  with  a  name. 


FILES 

/tmp/v*  temporaries 

SEE  ALSO 

lorder(l),  ld(l),  ranlib(l),  ar(5) 
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AR{1)  user  commands  AR(1) 

BUGS 

If  the  same  file  is  mentioned  twice  in  an  argument  list,  it  is  put  in  the  archive  twice. 

The  ‘last-modified’  date  of  a  file  will  not  be  altered  by  the  o  option  unless  the  user  is  either  the 
owner  of  the  extracted  file  or  the  super-user. 
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NAME 

as  —  mc68000  assembler 
SYNOPSIS 

as  1  -d2  ]  [  -j  !  [  -J  1  I  -h  I  [  -L  1  I  -R  ]  [  -o  objfile  |  file 
DESCRIPTION 

As  translates  assembly  code  in  the  named  file  into  executable  object  code  in  the  specified  objfile. 

All  undefined  symbols  in  the  assembly  are  treated  as  global. 

The  output  of  the  assembly  is  left  in  the  file  objfile.  If  the  — o  flag  is  omitted,  file  a. out  is  used. 
OPTIONS 

— d2  Specifies  that  instruction  offsets  involving  forward  or  external  references,  and  having 

sizes  unspecified  in  the  assembly  language  are  two  bytes  long.  The  default  is  four  bytes. 
See  also  the  — J  option 

— J  Suppress  span^dependent  instruction  calculations  and  force  all  branches  and  calls  to  take 

the  most  general  form.  This  is  used  when  assembly  time  must  be  minimized,  but  pro¬ 
gram  size  and  run  time  are  not  important. 

—h  Suppress  span-dependent  instruction  calculations  and  force  all  branches  to  be  of  medium 
length,  but  all  calls  to  take  the  most  general  form.  This  is  used  when  assembly  time 
must  be  minimized,  but  program  size  and  run  time  are  not  important.  This  option 
results  in  a  smaller  and  faster  program  than  that  produced  by  the  — J  option,  but  some 
very  large  programs  may  not  be  able  to  use  it  because  of  the  limits  of  the  medium-length 
branches. 

— L  Save  defined  labels  beginning  with  an  ‘L*,  which  are  normally  discarded  to  save  space  in 

the  resultant  symbol  table.  The  compilers  generate  such  temporary  labels. 

— J  Use  short  (pc-relative)  branches  to  resolve  jump’s  and  jsr’s  to  externals.  This  is  for  com¬ 

pact  programs  which  cannot  use  the  -d2  flag  because  of  large  program  relocation, 

— R  Make  initialized  data  segments  read-only  by  concatenating  them  to  the  text  segments. 

This  eliminates  the  need  to  run  editor  scripts  on  assembly  code  to  make  initialized  data 
read-only  and  shared, 

FILES 

/tmp/as*  default  temporary  file 

SEE  ALSO 

ld(l),  nm(l),  adb(l),  dbx(l),  a.out(6) 

The  ^Assembler  Reference  Manual  for  the  Sun  Workstation”  in  the  Sun  Programming  Tools 

Manual 


BUGS 

Should  assemble  standard  input  with  no  arguments. 

The  Pascal  compiler  (pc(l))  qualifies  a  nested  procedure  name  by  chaining  the  names  of  the 
enclosing  procedures.  This  sometimes  results  in  names  long  enough  to  abort  the  assembler, 
which  currently  limits  identifiers  to  512  characters. 
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NAME 

at  —  execute  commands  at  a  later  time 


SYNOPSIS 

at  time  [  day  ]  [  file  j 

DESCRIPTION 

At  squirrels  away  a  copy  of  the  named  file  (standard  input  default)  to  be  used  as  input  to  sh{l) 
or  C8k{l)  at  a  specified  later  time.  At  inserts  a  cd  command  to  the  current  directory  at  the 
beginning  of  the  copy  file,  and  follows  this  with  assignments  to  all  environment  variables  (except 
TERM,  which  is  useless  in  this  context.)  When  the  script  is  run,  it  uses  the  user  and  group  ID  of 
the  creator  of  the  copy  file. 

Time  is  specified  by  from  1  to  4  digits,  and  may  be  followed  by  ‘a’,  ‘p’,  ‘n’  or  for  AM,  PM, 
noon,  or  midnight  (letters  may  be  upper  or  lower  case).  One  and  two  digit  numbers  are  taken  to 
be  hours,  three  and  four  digits  to  be  hours  and  minutes.  If  no  letters  follow  the  digits,  a  24  hour 
clock  time  is  understood. 

Day  may  be  either  a  month  name  followed  by  a  day  number  —  for  example,  ‘apr  26*  —  or  a  day 
of  the  week  —  ‘weds*,  for  instance.  If  you  name  a  day  of  the  week  and  follow  this  with  the  word 
‘^eek*  —  ‘weds  week*  —  invocation  is  moved  seven  days  further  off.  Names  of  months  and  days 
may  be  recognizably  truncated. 

At  programs  are  executed  by  periodic  execution  of  the  command  luarllib/atrun  from  cro?i(S). 
The  granularity  of  at  depends  upon  how  often  atrun  is  executed. 

Standard  output  or  error  output  is  lost  unless  redirected. 

EXAMPLES 

Examples  of  legitimate  commands  are: 
at  8a  jan  24 
at  1530  fr  week 


FILES 

/usr/lib/atrun 


executor  (run  by  cr£)n(8)). 


in  /usr /spool/at: 

yy.ddd.hhhh.*  activity  for  year  yy,  day  dd,  hour  hhhh, 

lasttimedone  last  hhhh 

past  activities  in  progress 

SEE  ALSO 

calendar(l),  pwd(l),  sleep(l),  cron(8) 

BUGS 

Due  to  the  granularity  of  the  execution  of  f  usr/lib/atrun,  there  may  be  bugs  in  scheduling  things 
almost  exactly  24  hours  into  the  future. 
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USER  COMMANDS 


AWK(l) 


NAME 

awk  —  pattern  scanning  and  processing  language 
SYNOPSIS 

awk  (  — f  program_filt  [  [  — Fc  ]  (  program  ]  [  file  , , .  | 

DESCRIPTION 

Awk  scans  each  of  its  input  files  for  lines  that  match  any  of  a  set  of  patterns  specified  in  pro¬ 
gram.  The  input  files  are  read  in  order;  the  standard  input  is  read  if  there  are  no  files.  The 
filename  *  means  the  standard  input. 

The  set  of  patterns  may  either  appear  literally  on  the  command  line  as  program,  or,  by  using  the 
— f  option,  the  set  of  patterns  may  be  in  a  progratrLjile. 

With  each  pattern  in  program  there  can  be  an  associated  action  that  will  be  performed  when  a 
line  of  a  file  matches  the  pattern.  See  the  discussion  below  for  the  format  of  input  lines  and  the 
awk  language.  Each  line  in  each  input  file  is  matched  against  the  pattern  portion  of  every 
pattern- action  statement;  the  associated  action  is  performed  for  each  matched  pattern. 

OPTIONS 

*“f  program_file 

Use  the  contents  of  progratn_file  as  the  source  for  the  program, 

—F  c  Use  the  character  c  as  the  field  separator  (FS)  character.  See  the  discussion  of  FS  below. 

LINES,  STATEMENTS,  AND  THE  AWK  LANGUAGE 

Input  Lines 

An  input  line  is  made  up  of  fields  separated  by  white  space.  The  field  separator  can  be  changed 
by  using  FS  —  see  below.  Fields  are  denoted  $1,  $2,  up  to  $9;  $0  refers  to  the  entire  line. 

Pattern-action  Statements 

A  pattern-action  statement  has  the  form 

pattern  {  action  } 

A  missing  {  action  }  means  copy  the  line  to  the  output;  a  missing  pattern  always  matches. 

An  action  is  a  sequence  of  statements.  A  statement  can  be  one  of  the  following: 

if  (  conditional  )  statement  [  else  statement  ] 

while  (  conditional  )  statement 

for  (  expression  ;  conditional  ;  expression  )  statement 

break 

continue 

{  [  statement  j  •••  } 

variable  =  expression 

print  [  expression-list  |  [  >expression  | 

printf  format  [  ,  expression-list  |  (  >expression  | 

next  #  skip  remaining  patterns  on  this  input  line 

exit  #  skip  the  rest  of  the  input 

Format  of  the  Awk  Language 

Statements  are  terminated  by  semicolons,  newlines  or  right  braces.  An  empty  expression-list 
stands  for  the  whole  line. 

Expressions  take  on  string  or  numeric  values  as  appropriate,  and  are  built  using  the  operators  +, 
— »  /»  %>  and  concatenation  (indicated  by  a  blank).  The  C  operators  -I-+,  — ,  , 

/=,  and  are  also  available  in  expressions. 

Variables  may  be  scalars,  array  elements  (denoted  x[i])  or  fields.  Variables  are  initialized  to  the 
null  string.  Array  subscripts  may  be  any  string,  not  necessarily  numeric,  providing  a  form  of 
associative  memory.  String  constants  are  quoted 
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The  print  statement  prints  its  arguments  on  the  standard  output  (or  on  a  file  if  >file  is  present), 
separated  by  the  current  output  field  separator,  and  terminated  by  the  output  record  separator. 
The  prinif  statement  formats  its  expression  list  according  to  the  format  template  (see  printf{ZS) 
for  a  description  of  the  formatting  control  characters). 

Built  In  Functions 

The  built-in  function  length  returns  the  length  of  its  argument  taken  as  a  string,  or  of  the  whole 
line  if  no  argument.  There  are  also  built-in  functions  earp,  log^  sqrt^  and  ini,  where  truncates 
its  argument  to  an  integer.  sub$tr(s,  m,  n)  returns  the  n-character  substring  of  8  that  begins  at 
position  m.  The  sprinif (formal,  expr,  expr,  ..♦)  function  formats  the  expressions  according  to  the 
printf[3S)  format  given  by  format  and  returns  the  resulting  string. 

Patterns 

Patterns  are  arbitrary  Boolean  combinations  (!,  II,  fe&,  and  parentheses)  of  regular  expressions 
and  relational  expressions.  Regular  expressions  must  be  surrounded  by  slashes  and  are  as  in 
egrep.  Isolated  regular  expressions  in  a  pattern  apply  to  the  entire  line.  Regular  expressions  may 
also  occur  in  relational  expressions. 

A  pattern  may  consist  of  two  patterns  separated  by  a  comma;  in  this  case,  the  action  is  per¬ 
formed  for  all  lines  between  an  occurrence  of  the  first  pattern  and  the  next  occurrence  of  the 
second. 

A  relational  expression  is  one  of  the  following: 

expression  matchop  regular-expression 
expression  relop  expression 

where  a  relop  is  any  of  the  six  relational  operators  in  C,  and  a  matchop  is  either  “  (for  contains) 
or  (for  does  not  contain).  A  conditional  is  an  arithmetic  expression,  a  relational  expression,  or 
a  Boolean  combination  of  these. 

The  special  pattern  BEGIN  may  be  used  to  capture  control  before  the  first  input  line  is  read,  in 
which  case  BEGIN  must  be  the  first  pattern.  The  special  pattern  END  may  be  used  to  capture 
control  after  the  last  input  line  is  read,  in  which  case  END  must  be  the  last  pattern. 

Special  Variable  Names 

A  single  character  c  may  be  used  to  separate  the  fields  by  starting  the  program  with 
BEGIN  {  FS  =  ”c”  } 
or  by  using  the  -“Fc  option. 

Other  variable  names  with  special  meanings  include  NF,  the  number  of  fields  in  the  current 
record;  NR,  the  ordinal  number  of  the  current  record;  FILENAME,  the  name  of  the  current 
input  file;  OFS,  the  output  field  separator  (default  blank);  ORS,  the  output  record  separator 
(default  newline);  and  OFMT,  the  output  format  for  numbers  (default  ”%,6g"). 

EXAMPLES 

Print  lines  longer  than  72  characters: 
length  >  72 

Print  first  two  fields  in  opposite  order: 

{  print  $2,  $1  } 

Add  up  first  column,  print  sum  and  average: 

{  s  $1  } 

END  {  print  ’‘sum  is**,  s,  **  average  is**,  s/NR  } 

Print  fields  in  reverse  order: 
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{  for  (i  -  NF;  i  >  0;  — i)  print  $i  } 

Print  all  lines  between  start/stop  pairs: 

/start/,  /stop/ 

Print  all  lines  whose  first  field  is  different  from  previous  one: 

$1  !==  prev  {  print;  prev  $1  } 

SEE  ALSO 

lex(l),  sed(l) 

Pattern  Scanning  and  Procemng  with  Awk  in  the  Sun  Editing  and  Text  Processing  Manual. 

BUGS 

There  are  no  explicit  conversions  between  numbers  and  strings.  To  force  an  expression  to  be 
treated  as  a  number  add  0  to  it;  to  force  it  to  be  treated  as  a  string  concatenate  ****  to  it. 

Syntax  errors  result  in  the  cryptic  message  ^awk  hailing  out  near  line  1!!,^ 


22 


Last  change:  1  February  1985 


Sun  Release  2.0 


BASENAME(l) 


USER  COMMANDS 


BASENAME(l) 


NAME 

basename  —  strip  filename  affixes 
SYNOPSIS 

basename  string  [  suffix  | 

DESCRIPTION 

Basename  deletes  any  prefix  ending  in  7’  and  the  suffix,  if  present  in  string,  from  string,  and 
directs  the  result  to  the  standard  output*  It  is  normally  used  inside  substitution  marks  '  '  in 
shell  procedures, 

EXAMPLE 

This  shell  procedure  invoked  with  the  argument  /usr/$rc/cmd/cat,c  compiles  the  named  file  and 
moves  the  output  to  cat  in  the  current  directory: 

cc  $1 

mv  a.out  ^basename  $1  .c' 


SEE  ALSO 
sh(l) 
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NAME 

be  —  arbitrary- precision  arithmetic  language 
SYNOPSIS 

be  I  — c  ]  [  — 1  I  (  file  ...  ] 

DESCRIPTION 

Be  is  an  interactive  processor  for  a  language  which  resembles  C  but  provides  unlimited  precision 
arithmetic.  Be  takes  input  from  any  files  given,  then  reads  the  standard  input.  The  syntax  for 
be  programs  is  as  follows;  L  means  letter  a-z,  E  means  expression,  S  means  statement. 

Comments 

are  enclosed  in  /♦  and  ♦/. 

Names 

simple  variables:  L 
array  elements:  L  [  E  | 

The  words  Mbase*,  ‘obase*,  and  *scale’ 

Other  operands 

arbitrarily  long  numbers  with  optional  sign  and  decimal  point. 

(E) 

sqrt  (  E  ) 

length  (  E  )  number  of  significant  decimal  digits 

scale  (  E  )  number  of  digits  right  of  decimal  point 

L(E, •••,£) 

Operators 

+  —  *  /  %  "  (%  is  remainder;  "  is  power) 

H-f-  —  (prefix  and  postfix;  apply  to  names) 

<=»  >-!=<> 

=  +«  -=  ♦=  /x.  %=  "  = 

Statements 

E 

{  S  ;  ;  S  } 

if  (  E  )  S 
while  (  E  )  S 
for  (  E  ;  E  ;  E  )  S 
null  statement 
break 
quit 

Function  definitions 

define  L  (  L  L  )  { 
auto  L/, ... ,  Li 

S;  ...  S 

return  ( E  ) 

} 

Functions  in  —1  math  library 


5(X) 

sine 

c(x) 

cosine 

e(x) 

exponential 

l(x) 

log 

a(x) 

arctangent 

j(n,x) 

Bessel  function 
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All  function  arguments  are  passed  by  value. 

The  value  of  a  statement  that  is  an  expression  is  printed  unless  the  main  operator  is  an  assign¬ 
ment.  Either  semicolons  or  newlines  may  separate  statements.  Assignment  to  scale  influences 
the  number  of  digits  to  be  retained  on  arithmetic  operations  in  the  manner  of  rfc(l).  Assign¬ 
ments  to  ibase  or  obase  set  the  input  and  output  number  radix  respectively. 

The  same  letter  may  be  used  as  an  array,  a  function,  and  a  simple  variable  simultaneously.  All 
variables  are  global  to  the  program.  ‘Auto’  variables  are  pushed  down  during  function  calls. 
When  using  arrays  as  function  arguments  or  defining  them  as  automatic  variables  empty  square 
brackets  must  follow  the  array  name. 

EXAMPLES 

Define  a  function  to  compute  an  approximate  value  of  the  exponential  function: 
scale  —  20 
define  e(x){ 

auto  a,  b,  c,  i,  s 
a  =  1 
b  =  1 
s  =  l 

for(i=l;  1==1;  i++){ 
a  ^  a*x 
b  -  b*i 
c  =  a/b 

if(c  0)  return(s) 
s  s+c 

} 

} 


Print  approximate  values  of  the  exponential  function  of  the  first  ten  integers: 
for(i=l;  i<=10;  i-h-l-)  e(i) 

OPTIONS 

-“1  is  the  name  of  an  arbitrary  precision  math  library. 

— c  Compile  only:  be  is  actually  a  preprocessor  for  dc(l),  which  it  invokes  automatically, 

unless  the  — c  (compile  only)  option  is  present.  In  this  case  the  dc  input  is  sent  to  the 
standard  output  instead. 

FILES 

/usr/lib/lib.b  mathematical  library 
dc(l)  desk  calculator  proper 

SEE  ALSO 
dc(l) 

L.  L.  Cherry  and  R.  Morris,  J5C  —  An  arbitrary  precision  desk-calculator  language 

BUGS 

No  &&,  1 1,  or  !  operators. 

For  statement  must  have  all  three  E’s. 

Quit  is  interpreted  when  read,  not  when  executed. 
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NAME 

biff  —  mail  alarm 

SYNOPSIS 

biff  I  y|n  1 

DESCRIPTION 

Biff  informs  the  system  whether  you  want  to  be  notified  when  mail  arrives  during  the  current 
terminal  session.  The  command: 

biff  y 

enables  notification;  the  command: 

biff  n 

disables  it;  finally,  the  command: 

biff 

on  its  own  tells  you  whether  the  notification  is  y  or  n.  When  mail  notification  is  enabled,  the 
header  and  first  few  lines  of  the  message  are  printed  on  your  screen  whenever  mail  arrives. 
A  biff  y  command  is  often  included  in  the  file  Jogin  or  .profile  to  be  executed  at  each  login. 

operates  asynchronously.  For  synchronous  notification  use  the  MAIL  variable  of  aA(l)  or  the 
mail  variable  of  csA(l). 

SEE  ALSO 

csh(l),  sh(l),  mail(l) 
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NAME 

/bin/mail  —  send  or  receive  mail  among  users 
SYNOPSIS 

/bin/m&il  i  — 1 1  (  — P  1  I  — q  !  i  —t  filename  ] 

/bin/mail  [  -d  |  [  -I  j  [  — r  name  ]  person  ... 

DESCRIPTION 

Note:  This  is  the  old  version  7  UNIX  system  mail  program.  The  default  mail  command  is 
described  in  mail(l),  and  its  binary  is  in  the  directory  /usrjucb. 

/bin/ mail  with  no  argument  prints  a  user’s  mail,  message- by- message  in  last-in,  first-out  order. 
/bin/ mail  accepts  commands  from  the  standard  input  to  direct  disposition  messages. 

When  persons  are  named,  /bin/ mail  takes  the  standard  input  up  to  an  end-of-file  (or  a  line  with 
just  *•’)  and  adds  it  to  each  ‘mail*  file.  The  message  is  preceded  by  the  sender’s  name 

and  a  postmark.  Lines  that  look  like  postmarks  are  prepended  with  *>’.  A  person  is  usually  a 
user  name  recognized  by  login{l). 

If  there  is  any  pending  mail,  tells  you  there  is  mail  when  you  log  in.  It  is  also  possible  to 

have  the  C-Shell,  see  C8h{l)  or  the  comsat  daemon  tell  you  about  mail  that  arrives  while 

you  are  logged  in. 

OPTIONS 

Printing  Mail 

—I  continue  after  interrupts  —  an  interrupt  normally  terminates  the  /bin/mail  command 
and  leaves  the  mail  file  unchanged. 

— p  print  messages  without  prompting  for  commands.  Exit  immediately  upon  receiving  an 

interrupt. 

— q  quit  immediately  upon  interrupt. 

— *f  filename 

use  filename  as  if  it  were  the  mail  file. 

Sending  Mail 

— d  deliver  mail  directly,  don’t  route  the  message  through  sendmaiL  This  option  is  often 

used  by  programs  that  send  mail. 

—I  continue  after  interrupts  —  an  interrupt  normally  terminates  the  /hin/mail  command 
and  leaves  the  mail  file  unchanged. 

— r  name 

specify  a  string  to  appear  as  the  name  of  the  sender. 

COMMANDS 

r  print  a  command  summary. 

EOT  (control-D) 

put  unexamined  mail  back  in  the  mail  file  and  quit. 

Icommand 

escape  to  the  Shell  to  do  commands 
—  go  back  to  previous  message. 

+  go  on  to  next  message. 

newline 

go  on  to  next  message. 

d  delete  message  and  go  on  to  the  next, 
dq  delete  message  and  quit. 
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m  [  person  ]  ••• 

mail  the  message  to  the  named  persons  (yourself  is  default), 
n  go  on  to  next  message, 

p  print  message  (again), 

q  same  as  EOT. 


B  [  file  ] 

save  the  message  in  the  named  files  (‘mbox*  default). 
w  [file] 

save  the  message,  without  a  header,  in  the  named  files  (‘mbox’  default).  Delete  the  mes¬ 
sage  from  the  list  and  go  on  to  the  next  message. 

X  exit  without  changing  the  mail  file. 


FE.ES 

/etc/passwd  to  identify  sender  and  locate  persons 

/usr/spool/mail/^  incoming  mail  for  user  ♦ 

mbox  saved  mail 

/tmp/ma*  temp  file 

/usr/spooi/mail/*.lock  lock  for  mail  directory 

dead  .letter  unmailable  text 


SEE  ALSO 

biff(l),  write(l),  uucp(lC),  uux{lC),  xscnd(l),  sendmail(8) 

BUGS 

Race  conditions  sometimes  result  in  a  failure  to  remove  a  lock  file. 
Any  superuser  can  read  your  mail,  unless  it  is  sent  by  leend(l). 
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NAME 

cal  —  display  calendar 

SYNOPSIS 

cal  [  month  ]  year 

DESCRIPTION 

Cal  displays  a  calendar  for  the  specified  year.  If  a  month  is  also  specified,  a  calendar  for  that 
month  only  is  displayed. 

Year  can  be  between  1  and  9999.  Be  aware  that  ‘cal  78’  refers  to  the  early  Christian  era,  not  the 
20th  century.  Also,  the  year  is  always  considered  to  start  in  January,  even  though  this  is  histori¬ 
cally  naive. 

Month  is  a  number  between  1  and  12. 

The  calendar  produced  is  that  for  England  and  her  colonies. 

Try  September  1752. 
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NAME 

calendar  —  reminder  service 

SYNOPSIS 

calendar  [  —  ] 

DESCRIPTION 

Calendar  consults  the  file  calendar  in  the  current  directory  and  displays  lines  that  contain 
today’s  or  tomorrow’s  date  anywhere  in  the  line.  Most  reasonable  month-day  dates  —  such  as 
‘Dec.  7,’  ‘december  7/  and  ‘12/7’  —  are  recognized;  but  *7  December’  or  7/12’  are  not.  If  you 
give  the  month  as  with  a  date  —  for  example,  1”  —  that  day  in  any  month  will  do.  On 
weekends  ‘tomorrow’  extends  through  Monday. 

When  the  optional  —  argument  is  present,  calendar  does  its  job  for  every  user  who  has  a  file 
calendar  in  his  login  directory  and  sends  him  any  positive  results  by  maff(l).  Normally  this  is 
done  daily  in  the  wee  hours  under  control  of  cron(8). 

The  file  calendar  is  first  run  through  the  C  preprocessor,  llihlcppy  to  include  any  other  calendar 
files  specified  with  the  usual  “#include”  syntax.  Included  calendars  are  usually  shared  by  all 
users,  and  maintained  by  the  system  administrator. 

FILES 

“/calendar 

/usr /lib/calendar  to  figure  out  today’s  and  tomorrow’s  dates 

/etc/passwd 

/tmp/cal* 

/lib/cpp  subprocess 

/usr/bin/egrep  subprocess 
/bln/sed  subprocess 

/bin/mail  subprocess 

SEE  ALSO 

at(l),  cron(8),  mail(l) 

BUGS 

Calendar's  extended  idea  of  ‘tomorrow’  doesn’t  account  for  holidays. 


O  i 
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NAME 

cat  —  concatenate  and  display 
SYNOPSIS 

cat  [  -u  ]  I  -n  ]  1  -b  ]  I  -■  j  1  -V  I  I  -e  ]  1  -t  ]  I  —  I  I  file  ...  I 
DESCRIPTION 

Cat  reads  each  jilt  in  sequence  and  displays  it  on  the  standard  output.  Thus 

%  cat  goodies 

displays  the  contents  of  goodies  on  the  standard  output,  and 

%  cat  fllel  files  >file3 

concatenates  the  first  two  files  and  places  the  result  on  the  third. 

If  no  filename  argument  is  given,  or  if  the  argument  ’  is  given,  cat  reads  from  the  standard 
input  file.  If  the  standard  input  is  a  terminal,  input  is  terminated  by  a  ^D. 

OPTIONS 

— u  makes  the  output  completely  unbuffered.  If  — u  is  not  used,  output  is  buffered  in  1024* 

byte  blocks,  or  line-buffered  if  standard  output  is  a  terminal. 

— n  precedes  each  line  output  with  its  line  number. 

— b  numbers  the  lines,  as  — n,  but  omits  the  line  numbers  from  blank  lines. 

— B  substitutes  a  single  blank  line  for  multiple  adjacent  blank  lines. 

—V  displays  non-printing  characters  so  that  they  are  visible.  Control  characters  print  like 

for  contro!-x;  the  delete  character  (octal  0177)  prints  as  Non-ASCII  characters  (with 
the  high  bit  set)  are  displayed  as  M-  (for  meta)  followed  by  the  character  of  the  low  7 
bits. 

— e  displays  non-printing  characters,  as  and  in  addition  displays  a  *$’  character  at  the 

end  of  each  line. 

— t  displays  non-printing  characters,  as  — v,  and  in  addition  displays  tab  characters  as  ‘T. 

SEE  ALSO 

cp(l),  ex(l),  more(l),  pr(l),  tail(l) 

BUGS 

Beware  of  *cat  a  b  >a’  and  Vat  a  b  >b’,  which  destroy  the  input  files  before  reading  them. 
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NAME 

cb  —  C  program  beautifier 

SYNOPSIS 

cb 

DESCRIPTION 

Ch  places  a  copy  of  the  C  program  from  the  standard  input  on  the  standard  output  with  spacing 
and  indentation  that  displays  the  structure  of  the  program. 

SEE  ALSO 

indent(l) 


indent[i)  is  preferred. 
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NAME 

cc  —  C  compiler 
SYNOPSIS 

cc  I  —c  I  I  — g  ]  [  — o  output  ]  I  — O  1  1  — a  ]  1  —Aaamfiags  j  \  — B  string  \  (  — C  [ 

[  — D  name  |  [  — D  name^^def]  [  — E  |  [  — fslnglc  j  [  — fiiky  |  [  —go  [  |  —Idir  j  [  — p  ] 

[  -pg  ]  [  -R  I  [  -S  ]  I  -t[p|0jlj2||  [  -Uname  |  (  ~v  |  |  -w  ]  filename  ... 

DESCRIPTION 

Cc  is  the  UNIX  C  compiler  which  translates  programs  written  in  the  C  programming  language 
into  executable  load  modules,  or  into  relocatable  binary  programs  for  subsequent  loading  with 
the  W(l)  linker. 

In  addition  to  the  many  options,  cc  accepts  several  types  of  files.  Files  whose  names  end  with  .c 
are  taken  to  be  C  source  programs;  they  are  compiled,  and  each  resulting  object  program  is  left 
in  the  current  directory,  with  the  same  name  as  the  source  file,  except  that  the  *0  suffix  is 
replaced  by  .o.  In  the  same  way,  files  whose  names  end  with  mS  are  taken  to  be  assembly  source 
programs  and  are  assembled,  producing  a  file. 

Other  arguments  are  taken  to  be  loader  option  arguments,  object  programs,  or  libraries  of  object 
programs.  Unless  — c,  — S,  or  — B  is  specified,  these  programs  and  libraries,  together  with  the 
results  of  any  compilations  or  assemblies  specified,  are  loaded  (in  the  order  given)  to  produce  an 
executable  program  named  a. out.  The  name  a. out  can  be  overridden  with  the  loader’s  — o  name 
option. 

If  a  single  C  program  is  compiled  and  loaded  all  at  once,  the  intermediate  .o  file  is  deleted. 
OPTIONS 

The  following  options  are  interpreted  by  cc.  See  /d(l)  for  load-time  options. 

— c  Compile  only  —  suppress  the  loading  phase  of  the  compilation,  and  force  an  object  file 

to  be  produced  even  if  only  one  program  is  compiled. 

— g  Produce  additional  symbol  table  information  for  and  pass  the  — Ig  flag  to  /d(l). 

— o  output 

Name  the  final  output  file  output.  If  this  option  is  used,  the  file  a. out  is  left  undis¬ 
turbed. 

— O  /  Use  the  object  code  optimizer  to  improve  the  generated  code. 

—a  Insert  code  into  the  program  to  count  how  many  times  each  basic  block  in  the  program 

is  executed.  After  the  program  is  compiled  with  this  option,  there  will  be  a  .d  file  for 
every  *c  file.  The  ^d  file  accumulates  execution  data  for  the  corresponding  source  file. 
The  ^cct;(l)  utility  can  then  be  run  on  the  source  file  to  generate  statistics  about  the 
program.  This  process  is  performed  after  the  C  preprocessor  cpp(l)  has  run  but  before 
compilation  takes  place.  The  —a  option  must  be  used  when  linking  with  the  cc  or  Id 
command  as  well  as  the  compile  command. 

—Aaamflags 

Pass  asmfiags  to  the  assembler  as  in  its  command  line.  For  example,  — A— j  would  pass 
the  — J  option  to  tell  the  assembler  to  use  short  PC-relative  instructions  for  subroutine 
calls. 

—B  string 

Find  substitute  compiler  passes  in  the  files  named  string  with  the  suffixes  cpp,  ccom  and 
c2.  If  string  is  empty,  use  a  standard  backup  version. 

— C  Prevent  the  C  preprocessor  from  removing  comments. 

— Dname 

— Drtame=rfe/ 
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Define  name  to  the  preprocessor,  as  if  by  ‘#define\  If  no  definition  is  given,  the  name  is 
defined  as 

-E  Run  only  the  C  preprocessor  on  the  named  C  programs,  and  send  the  result  to  the  stan¬ 
dard  output, 

— fsingle 

Use  single-precision  arithmetic  in  computations  involving  only  float  numbers  —  that  is, 
do  not  convert  everything  to  double,  which  is  the  default.  Note  that  floating-point 
parameters  are  still  converted  to  double-precision,  and  functions  which  return  values 
still  return  double-precision  values.  Certain  programs  run  much  faster  using  this  option, 
but  be  aware  that  some  significance  can  be  lost  due  to  lower  precision  intermediate 
values. 

Generate  code  which  assumes  the  presence  of  a  SKY  floating-point  processor  board. 
Programs  compiled  with  this  option  can  only  be  run  in  systems  that  have  a  SKY  board 
installed.  Programs  compiled  without  the  — fsky  option  will  use  the  SKY  board  if  it  is 
present,  but  won’t  run  as  fast  as  they  would  if  the  —fsky  option  were  used.  If  any  part 
of  a  program  is  compiled  using  the  — feky  option,  you  must  also  use  this  option  when 
linking  with  the  cc  command,  since  a  different  set  of  startup  routines  is  used. 

Produce  additional  symbol  table  information  in  an  older  format  used  by  the  ad5(l) 
debugger  and  pass  the  — Ig  flag  to  W(l). 

‘#include’  files  whose  names  do  not  begin  with  always  sought  first  in  the  direc¬ 

tory  of  the  file  argument,  then  in  directories  named  in  —I  options,  then  in  the 
fust/ include  directory. 

Produce  profiling  code  to  count  the  number  of  times  each  routine  is  called.  If  loading 
takes  place,  replace  the  standard  startup  routine  by  one  that  automatically  calls  moni- 
for(3)  and  use  a  special  profiling  library  in  lieu  of  the  standard  C  library.  When  the 
program  is  run,  the  file  mon^out  is  created.  An  execution  profile  can  then  be  generated 
by  use  of  prof{l). 

Produce  profiling  code  in  the  manner  of  — p,  but  invokes  a  run-time  recording  mechan¬ 
ism  that  keeps  more  extensive  statistics  and  produces  a  gmon.out  file  at  normal  termi¬ 
nation.  gprof{l)  generates  an  execution  profile. 

Passed  on  to  aa,  making  initialized  variables  shared  and  read-only. 

Compile  the  named  C  programs  and  leave  the  assembly  language  output  on  correspond¬ 
ing  files  suffixed  .a. 

-t[p012| 

Find  only  the  designated  compiler  passes  in  the  files  whose  names  are  constructed  by  a 
— B  option.  In  the  absence  of  a  — B  option,  the  etring  is  taken  to  be  /usr/new/.  The 
letter/number  combinations  that  can  be  specified  for  the  — t  option  have  the  meanings: 
p  cpp  —  the  C  preprocessor. 

0  ccom  —  both  phases  of  the  C  compiler,  but  not  the  optimizer. 

1  Ignored  in  this  system  —  this  option  would  be  for  the  second  phase  of  a 
two-phase  compiler  but  in  the  Sun  system,  ccom  includes  both  phases. 

2  CJ?  —  the  object  code  optimizer. 

—IJname 

Remove  any  initial  definition  of  name. 

—y  Display  a  message  on  the  standard  error  file  indicating  the  argument  string  that  invoked 
each  phase  of  the  compiler. 

— w  Suppress  warning  messages. 


-faky 

-go 

—Idir 

-P 

-Pg 

-R 

-S 
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FILES 


file.c 

C  source  file 

file.s 

assember  source  file 

file.o 

object  file 

iile.a 

library  of  object  files 

a.out 

executable  output  file 

/tmp/ctm? 

temporary 

/lib/cpp 

macro  preprocessor 

/usr/lib/bb«count 

block  counting  preprocessor 

/lib/ccom 

compiler 

/lib/c2 

optional  optimizer 

/lib/crtO.o 

runtime  star  toff 

/lib/mcrtO.o 

startoff  for  profiling 

/usr/lib/gcrtO.o 

startoff  for  gprof-profiling 

/usr/lib/bbjink.o 

basic  block  counting  routine 

/lib/fcrtO.o 

SKY  runtime  startoff 

/lib/fmcrtO.o 

SKY  startoff  for  profiling 

/usr/lib/fgcrtO.o 

SKY  startoff  for  gprof-profiling 

/lib/libc.a 

standard  library,  see  m^ro(3) 

/usr/Iib/libc_p.a 

profiling  library,  see  tn^ro(3) 

/usr /include 

standard  directory  for  ‘#include’  files 

mon.out 

file  produced  for  analysis  by  prof{l) 

gmon.out 

file  produced  for  analysis  by  gprof{l) 

SEE  ALSO 

B.  W.  Kernighan  and  D.  M.  Ritchie,  The  C  Programming  Language,  Prentice-Hall,  1978 

UNIX  Programming  in  Programming  Tools  for  the  Sun  Workstation 

monitor(3),  prof(l),  gprof(l),  tcov(i),  adb(l),  ar(l),  ld(l),  dbx(l),  as(l),  diff(l),  cpp(l) 

DIAGNOSTICS 

The  diagnostics  produced  by  C  itself  are  intended  to  be  self-explanatory.  Occasional  obscure 
messages  may  be  produced  by  the  preprocessor,  assembler,  or  loader. 

BUGS 

Options  which  are  identical  to  cc  options  cannot  be  passed  loader. 

The  program  context  given  in  syntax  error  messages  is  taken  from  the  input  text  after  the  C 
preprocessor  has  performed  substitutions.  Therefore,  error  message  involving  syntax  errors  in  or 
near  macro  references  or  manifest  constants  may  be  misleading. 
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NAME 

cd  —  change  working  directory 

SYNOPSIS 

cd  I  directory  | 

DESCRIPTION 

Directory  becomes  the  new  working  directory.  The  process  must  have  execute  (search)  permis¬ 
sion  in  directory.  If  cd  is  used  without  arguments,  it  returns  you  to  your  login  directory.  In 
csh{l)  you  may  specify  a  list  of  directories  in  which  directory  is  to  be  sought  as  a  subdirectory  if 
it  is  not  a  subdirectory  of  the  current  directory;  see  the  description  of  the  cdpath  variable  in 
c$h{l). 

SEE  ALSO 

csh(I),  sh(l),  pwd(l),  chdir{2) 
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NAME 

cdc  —  change  the  delta  commentary  of  an  SCCS  delta 
SYNOPSIS 

/usr/ucb/Bccs/cdc  — rSID  [  — m  [mrlist]  ]  [  — y  [commentl  j  file  ... 

DESCRIPTION 

Cdc  changes  the  delta  commentary,  for  the  SID  specified  by  the  — r  option,  of  each  named  SCCS 
file. 

Delta  commentary  is  defined  to  be  the  Modification  Request  (MR)  and  comment  information  nor¬ 
mally  specified  via  the  delta{l)  command  (— m  and  — y  options). 

If  a  directory  is  named,  cdc  behaves  as  though  each  file  in  the  directory  were  specified  as  a 
named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with  s.) 
and  unreadable  files  are  silently  ignored.  If  a  name  of  —  is  given,  the  standard  input  is  read  (see 
WARNINGS);  each  line  of  the  standard  input  is  taken  to  be  the  name  of  an  SCCS  file  to  be  pro¬ 
cessed. 

Arguments  to  cdc,  which  may  appear  in  any  order,  consist  of  options  and  file  names. 

OPTIONS 

All  the  described  options  apply  independently  to  each  named  file: 

— r*5'/Z>  Specifies  the  5CCS  /Dentifi cation  {SID)  string  of  a  delta  for  which  the  delta  commen¬ 

tary  is  to  be  changed. 

—m  \  mrlist] 

If  the  SCCS  file  has  the  v  flag  set  (see  (idmm(l)),  a  list  of  MR  numbers  to  be  added 
and/or  deleted  in  the  delta  commentary  of  the  SID  specified  by  the  — r  option  may 
be  supplied.  A  null  MR  list  has  no  effect. 

MR  entries  are  added  to  the  list  of  MRs  in  the  same  manner  as  that  of  delta{\).  In 
order  to  delete  an  MR,  precede  the  MR  number  with  the  character  !  (see  EXAM¬ 
PLES),  If  the  MR  to  be  deleted  is  currently  in  the  list  of  MRs,  it  is  removed  and 
changed  into  a  “comment”  line.  A  list  of  all  deleted  MRs  is  placed  in  the  comment 
section  of  the  delta  commentary  and  preceded  by  a  comment  line  stating  that  they 
were  deleted. 

If  — m  is  not  used  and  the  standard  input  is  a  terminal,  the  prompt  MRb?  is  issued 
on  the  standard  output  before  the  standard  input  is  read;  if  the  standard  input  is  not 
a  terminal,  no  prompt  is  issued.  The  MRb?  prompt  always  precedes  the  commentBf 
prompt  (see  — y  option). 

MRs  in  a  list  are  separated  by  blanks  and/or  tab  characters.  An  unescaped  new-line 
character  terminates  the  MR  list. 

Note  that  if  the  v  flag  has  a  value  (see  a(imm(l)),  it  is  taken  to  be  the  name  of  a 
program  (or  shell  procedure)  which  validates  the  correctness  of  the  MR  numbers.  If 
a  non-zero  exit  status  is  returned  from  the  MR  number  validation  program,  cdc  ter¬ 
minates  and  the  delta  commentary  remains  unchanged. 

~-y\commeni\ 

Arbitrary  text  used  to  replace  the  comment[s)  already  existing  for  the  delta  specified 
by  the  — r  option.  The  previous  comments  are  kept  and  preceded  by  a  comment  line 
stating  that  they  were  changed.  A  null  comment  has  no  effect. 

If  — y  is  not  specified  and  the  standard  input  is  a  terminal,  the  prompt  comments? 
is  issued  on  the  standard  output  before  the  standard  input  is  read;  if  the  standard 
input  is  not  a  terminal,  no  prompt  is  issued.  An  unescaped  new-line  character  ter¬ 
minates  the  comment  text. 
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The  exact  permissions  necessary  to  modify  the  SCCS  file  are  documented  in  Source  Code  Control 
System,  Simply  stated,  they  are  either  (1)  if  you  made  the  delta,  you  can  change  its  delta  com¬ 
mentary;  or  (2)  if  you  own  the  file  and  directory  you  can  modify  the  delta  commentary* 

EXAMPLES 

tutorial%  cdc  -rl«5  -m*bi78-12a45  !bl77-54321  bl70-00001*  -ytrouble  B.file 

adds  bI78- 12345  and  bI7Q-00001  to  the  MR  list,  removes  bl77-54321  from  the  MR  list,  and  adds 
the  comment  trouble  to  delta  1*6  of  s.file* 

tutorial%  cdc  — rl*6  s.flle 
MRS?  !bl77-54321  bl78-12345  bl70-00001 
comments?  trouble 
does  the  same  thing, 

WARNINGS 

If  SCCS  file  names  are  supplied  to  the  cie  command  via  the  standard  input  (— •  on  the  command 
line),  then  the  — m  and  — y  options  must  also  be  used. 

FILES 

x-file  (see  delta{l)) 

z-file  (see  d€lta{l)) 

SEE  ALSO 

admin(l),  comb(l),  delta(l),  get(l),  help(l),  prs(l),  sccs(l),  sccsdiff(l),  sccsfile(5),  val(l),  what(l). 
Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 

DIAGNOSTICS 

Use  help{l)  for  explanations. 
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NAME 

checknews  —  check  if  user  has  news  on  the  USENET  news  network 
SYNOPSIS 

checknews  [  ynqew  ]  [  rtadnews  options  \ 

DESCRIPTION 

checknews  reports  to  the  user  whether  or  not  there  is  news. 

OPTIONS 

y  Reports  There  is  news’  if  the  user  has  news  to  read,  y  is  the  default  if  no  options  are 
specified. 

n  Reports  ‘No  news’  if  there  isn’t  any  news  to  read. 

q  Makes  checknews  quiet.  Instead  of  displaying  a  message,  the  exit  status  indicates  news.  A 
status  of  0  means  no  news,  1  means  there  is  news. 

V  alters  the  y  message  to  show  the  name  of  the  first  newsgroup  containing  unread  news.  Dou¬ 
bling  V  (that  is,  w)  displays  a  report  of  any  claim  of  new  news,  and  is  useful  if  checknews 
and  readnews  disagree  on  whether  there  is  news. 

e  Executes  readnews{l)  if  there  is  news. 

FILES 

“/.newsrc  Options  and  list  of  previously  read  articles 

/usr/lib/news/active  Active  newsgroups 

SEE  ALSO 

inews(l),  postnews(l),  readnews(l) 

Network  News  User*8  Guide  in  the  Beginner  *s  Guide  to  the  Sun  Workstation, 


Sun  Release  2.0 


Last  change:  6  March  1984 


39 


CHECKNR(l) 


USER  COMMANDS 


CHECKNR(l) 


NAME 

checknr  —  check  nroff/troff  files 
SYNOPSIS 

checknr  [  -«  ]  (  -f  1  I  .xl.yUx2.y2  . . ,  •zn.yn  )  [  -c  .xLx2.xS  . . .  .a?n  )  ]  filename  ,,,  ] 
DESCRIPTION 

Checknr  checks  a  list  of  nro^(l)  or  troff{l)  input  files  for  certain  kinds  of  errors  involving 
mismatched  opening  and  closing  delimiters  and  unknown  commands.  ^If  no  files  are  specified, 
checknr  checks  the  standard  input.  Delimiters  checked  are: 

(1)  Font  changes  using  \f:r  ...  \fP. 

(2)  Size  changes  using  \sa: ...  \s0. 

(3)  Macros  that  come  in  open  •••  close  forms,  for  example,  the  .TS  and  .TE  macros  which 
must  always  come  in  pairs. 

Checknr  knows  about  the  m${7)  and  me(7)  macro  packages. 

Checknr  is  intended  to  be  used  on  documents  that  are  prepared  with  checknr  in  mind.  It  expects 
a  certain  document  writing  style  for  \f  and  \s  commands,  in  that  each  \fx  must  be  terminated 
with  \fP  and  each  \sx  must  be  terminated  with  \s0.  While  it  will  work  to  directly  go  into  the 
next  font  or  explicitly  specify  the  original  font  or  point  size,  and  many  existing  documents  actu¬ 
ally  do  this,  such  a  practice  will  produce  complaints  from  checknr.  Since  it  is  probably  better  to 
use  the  \fP  and  \s0  forms  anyway,  you  should  think  of  this  as  a  contribution  to  your  document 
preparation  style. 

OPTIONS 

—8  Ignore  \s  size  changes. 

— f  Ignore  \f  font  changes. 

—a  Add  pairs  of  macros  to  the  list.  The  pairs  of  macros  are  assumed  to  be  those  (such  as 
.DS  and  .DE)  that  should  be  checked  for  balance.  The  —a  option  must  be  followed  by 
groups  of  six  characters,  each  group  defining  a  pair  of  macros.  The  six  characters  are  a 
period,  the  first  macro  name,  another  period,  and  the  second  macro  name.  For  example, 
to  define  a  pair  .BS  and  .ES,  use  — a.BS*ES 

— c  define  commands  which  checknr  would  otherwise  complain  about  as  undefined. 

SEE  ALSO 

nroff(l),  troff(l),  ms(7),  me(7),  checkeq(l) 

BUGS 

There  is  no  way  to  define  a  1  character  macro  name  using  —a 
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NAME 

chgrp  —  change  group 
SYNOPSIS 

chgrp  I  — f  ]  group  file 
DESCRIPTION 

Chgrp  changes  the  group-ID  of  the  files  to  group.  The  group  may  be  either  a  decimal  GID  or  a 
group  name  found  in  the  group-ID  file. 

The  user  invoking  chgrp  must  belong  to  the  specified  group  and  be  the  owner  of  the  file,  or  be 
the  super-user. 

No  errors  are  reported  when  the  — f  (force)  option  is  given. 

FILES 

/etc/group 
SEE  ALSO 

chown(2),  passwd(5),  group(5) 


o 
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NAME 

chmod  —  change  mode 

SYNOPSIS 

chmod  mode  file  . . . 

DESCRIPTION 

The  mode  of  each  named  file  is  changed  according  to  mode,  which  may  be  absolute  or  symbolic. 
An  absolute  mode  is  an  octal  number  constructed  from  the  OR  of  the  following  modes: 


4000 

set  user  ID  on  execution 

2000 

set  group  ID  on  execution 

1000 

sticky  bit,  see  chmod(2) 

0400 

read  by  owner 

0200 

write  by  owner 

0100 

execute  (search  in  directory)  by  owner 

0070 

read,  write,  execute  (search)  by  group 

0007 

read,  write,  execute  (search)  by  others 

A  symbolic 

:  mode  has  the  form: 

[  who  ]  op  permission  [  op  permission  |. .. 

The  who  part  is  a  combination  of  the  letters  u  (for  user’s  permissions),  s  (group)  and  o  (other). 
The  letter  a  stands  for  all,  or  ugo.  If  who  is  omitted,  the  default  is  a  but  the  setting  of  the  file 
creation  mask  (see  umask(2))  is  taken  into  account. 

Op  can  be  +  to  add  permission  to  the  file’s  mode,  —  to  take  away  permission  and  —  to  assign 
permission  absolutely  (all  other  bits  for  that  category,  owner,  group,  or  others,  will  be  reset). 

Permission  is  any  combination  of  the  letters  r  (read),  w  (write),  x  (execute),  a  (set  owner  or 
group  id)  and  t  (save  text  —  sticky).  Letters  u,  g  or  o  indicate  that  permission  is  to  be  taken 
from  the  current  mode.  Omitting  permission  is  only  useful  with  =«  to  take  away  all  permissions. 

EXAMPLES 

The  first  example  denies  write  permission  to  others,  the  second  makes  a  file  executable: 

chmod  o— w  file 
chmod  +x  file 

Multiple  symbolic  modes  separated  by  commas  may  be  given.  Operations  are  performed  in  the 
order  specified.  The  letter  a  is  only  useful  with  u  or  g. 

Only  the  owner  of  a  file  (or  the  super-user)  may  change  its  mode. 

SEE  ALSO 

ls(l),  chmod(2),  stat(2),  umask(2),  chown(8) 
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NAME 

chsh  -  change  default  login  shell 
SYNOPSIS 

chsh  username  j  shell  j 
DESCRIPTION 

Chsh  changes  the  login  shell  field  of  the  user’s  password  file  entry.  If  no  shell  is  specified,  the 
shell  reverts  to  the  default  login  shell  /bin/sh.  To  specify  a  shell  other  than  /binfcsh,  you  must 
be  the  super-user. 

EXAMPLES 

angel%  chsh  bill  /bln/esh 

SEE  ALSO 

csh(l),  passwd(l),  passwd(5) 
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NAME 

clear  —  clear  screen 

SYNOPSIS 

clear 

DESCRIPTION 

Clear  clears  your  screen  if  this  is  possible.  It  looks  in  the  environment  for  the  terminal  type  and 
then  in  /etc/termcap  to  figure  out  how  to  clear  the  screen. 

FILES 

/etc/termcap  terminal  capability  data  base 
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NAME 

clear_colorinap  —  clear  the  color  map 

SYNOPSIS 

clear  „color  map 

DESCRIPTION 

Clear_colormap  clears  your  hardware  colormap. 
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NAME 

clocktool  —  display  the  time  in  a  window 
SYNOPSIS 

clocktool  [  — s  I  [  — 1 1  [  — r  ]  [  — d  mdyaw  I  [  — f  I 
DESCRIPTION 

Clocktool  displays  the  current  time  in  a  window.  While  it  is  open  it  prints  the  date  and  time  in 
its  window;  when  it  is  closed,  its  icon  is  a  clock  face  which  keeps  time. 

OPTIONS 

— r  causes  clocktool  to  use  a  square  face  with  roman  numerals  in  the  iconic  state.  This 
replaces  the  default  round  clock  face. 

— d  display  date  information  in  a  small  area  just  below  the  clock  face.  The  date  information 
to  be  displayed  may  include: 

m  the  month, 

d  the  day  of  the  month  (1-31), 

y  the  year, 

a  the  string  AM  or  PM,  as  appropriate, 

w  the  day  of  the  week  (Sun— Sat). 

There  is  only  room  for  3  of  these,  but  any  3  may  be  displayed  in  any  sequence. 

— s  start  clocktool  with  the  seconds  turned  on.  By  default,  the  clock  starts  with  seconds 

turned  off,  and  updates  every  minute.  With  seconds  turned  on,  it  updates  every  second, 
and,  if  iconic,  displays  a  second  hand. 

— t  Ignore  the  real  time,  and  instead  run  in  a  loop  continuously  incrementing  the  time  by  one 

minute  and  displaying  it. 

— f  Display  the  date  and  day  of  week  on  the  clock  face. 

Clocktool  also  accepts  all  of  the  generic  tool  arguments  discussed  in  8nntoolB{l), 

ClocktooVs  window  is  not  a  terminal  subwindow;  it  provides  the  Tool  Manager  menu  if  you 
depress  the  menu  button  in  it.  However,  it  listens  for  keyboard  input,  toggling  its  state  on  two 
letters  (case  does  not  matter): 

s  toggles  the  display  of  seconds. 

t  toggles  the  ‘test*  mode. 

You  can  only  modify  these  states  while  the  clock  is  open;  when  it  is  iconic,  it  responds  with  the 
standard  Tool  Manager  functions  to  mouse  and  keyboard  input. 

SEE  ALSO 

8untool${l), 

FILES 

/usr/lib/fonts/fixedwidthfonts/sail.r.6 

BUGS 

There  should  be  a  way  to  change  the  date  information  on  the  fly. 

The  date  display  doesn’t  go  well  with  the  round  clock  face. 
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NAME 

cmp  —  compare  two  files 
SYNOPSIS 

cmp  I  — I  ]  (  — •  1  filel  file2 
DESCRIPTION 

Cmp  compares  filel  and  fileS.  If  filel  is  cmp  reads  from  the  standard  input.  Under  default 
options,  cmp  makes  no  comment  if  the  files  are  the  same;  if  they  differ,  it  announces  the  byte  and 
line  number  at  which  the  difference  occurred.  If  one  file  is  an  initial  subsequence  of  the  other, 
that  fact  is  noted. 

OPTIONS 

—1  Print  the  byte  number  (decimal)  and  the  differing  bytes  (octal)  for  each  difference. 

—8  Print  nothing  for  differing  files;  return  codes  only. 

SEE  ALSO 

diff(l),  comm(l) 

DIAGNOSTICS 

Exit  code  0  is  returned  for  identical  files,  1  for  different  files,  and  2  for  an  inaccessible  or  missing 
argument. 
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NAME 

col  —  filter  reverse  paper  motions 

SYNOPSIS 

col  [  — bfx  J 

DESCRIPTION 

Col  copies  the  standard  input  to  the  standard  output  and  performs  line  overlays  implied  by 
reverse  line  feeds  (ESC-7  in  ASCII)  and  by  forward  and  reverse  half  line  feeds  (ESC-9  and  ESC- 
8),  Col  is  particularly  useful  for  filtering  multicolumn  output  made  with  the  ‘.rt'  command  of 
nroff  and  output  resulting  from  use  of  the  tbl{l)  preprocessor. 

The  control  characters  SO  (ASCII  code  017),  and  SI  (016)  are  assumed  to  start  and  end  text  in 
an  alternate  character  set.  The  character  set  (primary  or  alternate)  associated  with  each  print¬ 
ing  character  read  is  remembered;  on  output,  SO  and  SI  characters  ar>  generated  where  neces¬ 
sary  to  maintain  the  correct  treatment  of  each  character. 

All  control  characters  are  removed  from  the  input  except  space,  backspace,  tab,  return,  newline, 
ESC  (033)  followed  by  one  of  7,  8,  9,  SI,  SO,  and  VT  (013).  This  last  character  is  an  alternate 
form  of  full  reverse  line  feed,  for  compatibility  with  some  other  hardware  conventions.  Ail  other 
non-printing  characters  are  ignored. 

OPTIONS 

“f  Fine:  although  col  accepts  half  line  motions  in  its  input,  it  normally  does  not  emit  them 
on  output.  Instead,  text  that  would  appear  between  lines  is  moved  to  the  next  lower  full 
line  boundary.  The  — f  option  suppresses  this  treatment  —  in  this  case  the  output  from 
col  may  contain  forward  half  line  feeds  (ESC-9),  but  will  still  never  contain  either  kind  of 
reverse  line  motion. 

— b  Col  assumes  that  the  output  device  in  use  is  not  capable  of  backspacing.  In  this  case,  if 

several  characters  are  to  appear  in  the  same  place,  only  the  last  one  read  will  be  taken. 

—X  Do  not  convert  white  space  to  tabs  to  shorten  printing  time. 

SEE  ALSO 

trofT(l),  tbl(l) 

BUGS 

Can’t  back  up  more  than  128  lines. 

No  more  than  800  characters,  including  backspaces,  on  a  line. 
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NAME 

colcrt  —  filter  nroff  output  for  CRT  previewing 
SYNOPSIS 

colcrt  I  —  ]  I  — 2  ]  [  file  ...  ] 

DESCRIPTION 

Colcrt  provides  virtual  halMine  and  reverse  line  feed  sequences  for  terminals  without  such  capa¬ 
bility,  and  on  which  overstriking  is  destructive.  Half-line  characters  and  underlining  (changed  to 
dashing  are  placed  on  new  lines  in  between  the  normal  output  lines. 

OPTIONS 

—  Suppress  all  underlining  —  especially  useful  for  previewing  allboxed  tables  from  tbl{l), 

—2  Print  all  half-lines,  effectively  double  spacing  the  output.  Normally,  a  minimal  space  out¬ 

put  format  is  used  which  suppresses  empty  lines,  Colcrt  never  suppresses  two  consecu¬ 
tive  empty  lines,  however.  The  —2  option  is  useful  for  sending  output  to  the  line  printer 
when  the  output  contains  superscripts  and  subscripts  which  would  otherwise  be  invisible. 

EXAMPLE 

A  typical  use  of  colcrt  would  be 

tbl  exum2.n  j  nroff  —ms  [  colcrt  —  j  more 

SEE  ALSO 

nroff(l),  troff(l),  col(l),  more(l),  ul(l) 

BUGS 

Should  fold  underlines  onto  blanks  even  with  the  ’  option  so  that  a  true  underline  character 
would  show;  if  we  did  this,  however,  colcrt  wouldn’t  get  rid  of  cti'd  underlining  completely. 

Can’t  back  up  more  than  102  lines. 

General  overstriking  is  lost;  as  a  special  case  ‘j’  overstruck  with  ’  or  underline  becomes  ‘H-’* 
Lines  are  trimmed  to  132  characters. 

Some  provision  should  be  made  for  processing  superscripts  and  subscripts  in  documents  which 
are  already  double-spaced. 
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NAME 

coirm  —  remove  columns  from  a  file 
SYNOPSIS 

coirm  (  startcol  (  endcol  |  | 

DESCRIPTION 

Coirm  removes  selected  columns  from  a  text  file.  The  text  is  is  taken  from  standard  input  and 
copied  to  the  standard  output  with  the  specified  columns  removed. 

If  only  startcol  is  specified,  the  columns  of  each  line  are  removed  starting  with  startcol  and 
extending  to  the  end  of  the  line.  If  both  startcol  and  endcol  are  specified,  all  columns  between 
startcol  and  endcol,  inclusive,  are  removed. 

Column  numbering  starts  with  column  1. 

SEE  ALSO 

expand(l) 
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NAME 

comb  —  combine  SCCS  deltas 
SYNOPSIS 

/usr/sccs/comb  |  j  [  — •  ]  [  — pS/Z)  j  [  — clist  ]  filename  ••• 

DESCRIPTION 

Comb  generates  a  shell  procedure  (see  which,  when  run,  will  reconstruct  the  given  SCCS 

files.  If  a  directory  is  named,  comb  behaves  as  though  each  file  in  the  directory  were  specified  as 
a  named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with  b*) 
and  unreadable  files  are  silently  ignored.  If  a  name  of  —  is  given,  the  standard  input  is  read; 
each  line  of  the  standard  input  is  taken  to  be  the  name  of  an  SCCS  file  to  be  processed;  non-SCCS 
files  and  unreadable  files  are  silently  ignored.  The  generated  shell  procedure  is  written  on  the 
standard  output. 

OPTIONS 

Options  are  explained  as  though  only  one  named  file  is  to  be  processed,  but  the  effects  of  any 
option  apply  independently  to  each  named  file. 

-pSID  The  5CCS  /Dentification  string  (SID)  of  the  oldest  delta  to  be  preserved.  All  older  deltas 
are  discarded  in  the  reconstructed  file. 

—clist  A  list  of  deltas  to  be  preserved.  All  other  deltas  are  discarded.  See  g€t{l)  for  the  syntax 
of  a  list 

— o  For  each  get  — e  generated,  the  reconstructed  file  is  accessed  at  the  release  of  the  delta 

to  be  created.  In  the  absence  of  the  —o  option,  the  reconstructed  file  is  accessed  at  the 
most  recent  ancestor.  Use  of  the  — o  option  may  decrease  the  size  of  the  reconstructed 
SCCS  file.  It  may  also  alter  the  shape  of  the  delta  tree  of  the  original  file. 

—8  Generate  a  shell  procedure  which,  when  run,  will  produce  a  report  giving,  for  each  file: 
the  file  name,  size  (in  blocks)  after  combining,  original  size  (also  in  blocks),  and  percen¬ 
tage  change  computed  by: 

100  ♦  (original  —  combined)  /  original 

It  is  recommended  that  before  any  SCCS  files  are  actually  combined,  you  should  use  this 
option  to  determine  exactly  how  much  space  is  saved  by  the  combining  process. 

If  no  options  are  specified,  comb  preserves  only  leaf  deltas  and  the  minima!  number  of  ancestors 
needed  to  preserve  the  tree. 

FILES 

s.COMB  The  name  of  the  reconstructed  SCCS  file, 

comb?????  Temporary. 

SEE  ALSO 

sccs(l),  admin(l),  delta(l),  get(l),  help(l),  prs(l),  sccsfile(5). 

Source  Code  Control  System  \n  Programming  Tools  for  the  Sun  Workstation. 

DIAGNOSTICS 

Use  help{l)  for  explanations. 

BUGS 

Comb  may  rearrange  the  shape  of  the  tree  of  deltas.  It  may  not  save  any  space;  in  fact,  it  is  pos¬ 
sible  for  the  reconstructed  file  to  actually  be  larger  than  the  original. 
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NAME 

comm  —  select  or  reject  lines  common  to  two  sorted  files 
SYNOPSIS 

comm  I  -  I  123  I  I  filel  file2 
DESCRIPTION 

Comm  reads  filel  and  fileS,  which  should  be  ordered  in  ASCII  collating  sequence,  and  produces  a 
three  column  output:  lines  only  in  filel;  lines  only  in  fileg;  and  lines  in  both  files.  The  filename 
’  means  the  standard  input. 

Flags  1,  2,  or  3  suppress  printing  of  the  corresponding  column.  Thus  comm  —12  prints  only  the 
lines  common  to  the  two  files;  comm  —23  prints  only  lines  in  the  first  file  but  not  in  the  second; 
comm  —123  does  nothing. 

SEE  ALSO 

cmp(l),  diff(l),  uniq(l) 
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NAME 

compact,  uncompact,  ccat  —  compress  and  uncompress  files,  and  cat  them 
SYNOPSIS 

compact  I  filename  •••  | 
uncompact  [  filename  •••  ] 
ccat  I  filename  •••  | 

DESCRIPTION 

Compact  compresses  the  named  files  using  an  adaptive  Huffman  code.  If  no  file  names  are  given, 
the  standard  input  is  compacted  to  the  standard  output.  Compact  operates  as  an  on-line  algo¬ 
rithm.  Each  time  a  byte  is  read,  it  is  encoded  immediately  according  to  the  current  prefix  code. 
This  code  is  an  optimal  Huffman  code  for  the  set  of  frequencies  seen  so  far.  It  is  unnecessary  to 
prepend  a  decoding  tree  to  the  compressed  file  since  the  encoder  and  the  decoder  start  in  the 
same  state  and  stay  synchronized.  Furthermore,  compact  and  uncompact  can  operate  as  filters. 
In  particular: 

•  ••  j  compact  [  uncompact  j  ••• 
operates  as  a  (very  slow)  no-op. 

When  an  argument  file  is  given,  it  is  compacted  and  the  resulting  file  is  placed  in  file,C;  file  is 
removed.  The  first  two  bytes  of  the  compacted  file  code  the  fact  that  the  file  is  compacted.  This 
code  is  used  to  prohibit  recompaction. 

The  amount  of  compression  to  be  expected  depends  on  the  type  of  file  being  compressed.  Typical 
values  of  compression  are:  Text  (38%),  Pascal  Source  (43%),  C  Source  (36%)  and  Binary  (19%). 
These  values  are  the  percentages  of  file  bytes  reduced. 

Uncompact  restores  the  original  file  from  a  file  called  which  was  compressed  by  compact.  If 

no  file  names  are  given,  the  standard  input  is  uncompacted  to  the  standard  output. 

Ccat  cats  the  original  file  from  a  file  compressed  by  compact,  without  uncompressing  the  file. 

FILES 

*,C  compacted  file  created  by  compact,  removed  by  uncompact 

SEE  ALSO 

Gallager,  Robert  G.,  ‘Variations  on  a  Theme  of  Huffman*,  LE,E,E,  Transactions  on  Information 
Theory,  vol.  IT-24,  no.  6,  November  1978,  pp.  668  -  674. 
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NAME 

cp  —  copy  files 
SYNOPSIS 

cp  I  -i  I  I  -r  I  filel  file2 
cp  I  — i  I  I  — r  I  file  ...  directory 
DESCRIPTION 

Filel  is  copied  onto  fileS.  The  mode  and  owner  of  fileS  are  preserved  if  it  already  existed;  the 
mode  of  the  source  file  is  used  otherwise. 

In  the  second  form,  one  or  more  files  are  copied  into  the  directory  with  their  original  file-names. 
Cp  refuses  to  copy  a  file  onto  itself. 

OPTIONS 

—I  Interactive:  prompt  the  user  with  the  name  of  the  file  whenever  the  copy  would 
overwrite  an  old  file.  Answering  with  ’y’  means  that  cp  should  go  ahead  and  copy  the 
file.  Any  other  answer  will  prevent  cp  from  overwriting  the  file. 

— r  Recursive:  if  any  of  the  source  files  are  directories,  cp  copies  each  subtree  rooted  at  that 

name;  in  this  case  the  destination  must  be  a  directory. 

EXAMPLES 

To  make  a  backup  copy  of  goodies: 

%  cp  goodies  old.goodiet 

To  copy  an  entire  directory  hierarchy: 

%  cp  — r  /uar/wendy/erc  /usr/wendy/backup 
However,  BEWARE  of  a  recursive  copy  like  this  one: 

%  cp  — r  /usr/wendy/src  /usr/wendy/src/backup 

which  keeps  copying  files  until  it  fills  the  entire  file  system. 

SEE  ALSO 

cat(l),  pr(l),  mv(l),  rcp(lC) 

BUGS 

There  should  be  an  option  to  copy  timestamps  to  the  new  files  —  for  instance,  when  copying  a 
whole  hierarchy  from  one  file  system  to  another  file  system,  or  when  making  a  backup  copy. 
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NAME 

cpio  —  copy  file  a^rchives  in  and  out 

SYNOPSIS 

cplo  — o  [  acBvs  I 

cpio  —1  [  Bcdmrtuv6*  |  [  patterns  ] 
cplo  — p  [  adlmruv#  j  directory 
DESCRIPTION 

Cpio  -o  (copy  out)  reads  the  standard  input  to  get  a  list  of  pathnames,  and  then  copies  those 
files  onto  the  standard  output,  together  with  pathname  and  status  information. 

Cpio  -*1  (copy  in)  reads  the  standard  input  (which  is  assumed  to  be  the  product  of  a  previous 
Cpio  — o  command),  to  get  a  list  of  files  selected  by  zero  or  more  patterns  as  defined  in  the 
name-generating  notation  of  sh{l)  or  ceh{iy  In  patterns,  the  meta-characters  ?,  ♦,  and  [. ..| 
match  the  slash  (/)  character.  The  default  for  patterns  is  ♦  (select  all  files). 

Cpio  — p  (pass)  copies  out  and  in  in  a  single  operation.  Destination  pathnames  are  interpreted 
relative  to  the  named  directory. 

OPTIONS 

a 

B 

d 
c 

T 

t 

U 

V 

1 

m 

6 
8 

EXAMPLES 

To  copy  the  contents  of  a  directory  into  an  archive: 

%  is  }  cplo  — o  >  /dev/mtO 

To  duplicate  the  o/rfdir  directory  hierarchy  in  the  directory: 

%  cd  olddir 

%  find  •  —print }  cplo  —pdl  newdlr 

Some  forms  of  cpio  tapes  from  other  sites  have  the  bytes  swapped  in  the  file.  The  8  option 
doesn’t  help  since  it  only  swaps  the  data  bytes  and  not  the  header.  To  overcome  this  problem, 
use  dd  with  the  conv— swab  option  to  swap  alt  pairs  of  bytes  (including  the  header),  then  pipe 
the  output  of  dd  through  cpio  with  the  s  option  to  swap  the  data  bytes  back  again: 

%  dd  If=u;Afl^et;er  the  file  is  conv=8wab  }  cpio  —is 


Reset  the  access  times  of  input  files  after  they  have  been  copied. 

Input/output  is  to  be  blocked  at  5120  bytes  to  the  record.  This  does  not  apply  to  the 
pass  option.  This  option  is  only  meaningful  with  data  directed  to  or  from  /dev/rmtf 

Directories  should  be  created  as  needed. 

Write  header  information  in  ASCII  character  form  for  portability. 

Interactively  rename  files.  If  the  user  types  a  null  line,  the  file  is  skipped. 

Print  a  Table  of  contents  of  the  input.  No  files  are  created. 

Copy  unconditionally.  Normally,  an  older  file  will  not  replace  a  newer  file  with  the  same 
name. 

Verbose  option.  A  list  of  filenames  is  displayed.  When  used  with  the  t  option,  the  table 
of  contents  looks  like  the  output  of  an  Is  —I  command  (see  /^(1)J. 

Whenever  possible,  link  files  rather  than  copying  them.  Usable  only  with  the  — p  option. 

Retain  previous  file  modification  time.  This  option  is  ineffective  on  directories  that  are 
being  copied. 

Process  an  old  (version  6  UNIX  system)  file.  This  is  only  useful  with  —I  (copy  in). 

Swaps  pairs  of  data  bytes.  Note  that  the  a  option  cannot  be  used  with  the  c  option. 
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SEE  ALSO 

ar(l),  find(l),  cpio(5) 

BUGS 

Pathnames  are  restricted  to  128  characters.  If  there  arc  too  many  unique  linked  files,  cpio  runs 
out  of  memory  to  keep  track  of  them  and  linking  information  is  lost  thereafter.  Only  the  super- 
user  can  copy  special  files. 
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NAME 

crypt  —  encode/decode 

SYNOPSIS 

crypt  [  password  ] 

DESCRIPTION 

Crypt  encrypts  and  decrypts  the  contents  of  a  file.  Crypt  reads  from  the  standard  input  and 
writes  on  the  standard  output.  The  password  is  a  key  that  selects  a  particular  transformation. 
If  no  password  is  given,  crypt  demands  a  key  from  the  terminal  and  turns  off  printing  while  the 
key  is  being  typed  in.  Crypt  encrypts  and  decrypts  with  the  same  key: 
tutorial%  crypt  key  <clear.file  >encrypted*flle 
tutorial^  crypt  key  <encrypted«flle  {  pr 
will  print  the  contents  of  clear,file. 

Files  encrypted  by  crypt  are  compatible  with  those  treated  by  the  editors  ed(l),  ex{l)  and  in 
encryption  mode. 

The  security  of  encrypted  files  depends  on  three  factors:  the  fundamental  method  must  be  hard 
to  solve;  direct  search  of  the  key  space  must  be  infeasible;  ‘sneak  paths’  by  which  keys  or  dear- 
text  can  become  visible  must  be  minimized. 

Crypt  implements  a  one-rotor  machine  designed  along  the  lines  of  the  German  Enigma,  but  with 
a  255-element  rotor.  Methods  of  attack  on  such  machines  are  known,  but  not  widely;  moreover 
the  amount  of  work  required  is  likely  to  be  large. 

The  transformation  of  a  key  into  the  internal  settings  of  the  machine  is  deliberately  designed  to 
be  expensive,  that  is,  to  take  a  substantial  fraction  of  a  second  to  compute.  However,  if  keys  are 
restricted  to  (say)  three  lower-case  letters,  then  encrypted  files  can  be  read  by  expending  only  a 
substantial  fraction  of  five  minutes  of  machine  time. 

Since  the  key  is  an  argument  to  the  crypt  command,  it  is  potentially  visible  to  users  executing 
p5(l)  or  a  derivative.  To  minimize  this  possibility,  crypt  takes  care  to  destroy  any  record  of  the 
key  immediately  upon  entry.  No  doubt  the  choice  of  keys  and  key  security  are  the  most  vulner¬ 
able  aspect  of  crypt, 

FILES 

/dev/tty  for  typed  key 
SEE  ALSO 

ed(l),  ex(l),  makekey(8)  and  vl(l) 

RESTRICTIONS 

This  program  is  not  available  on  software  shipped  outside  the  U.S. 


Sun  Release  2.0 


Last  change:  1  February  1985 


57 


CSH(l) 


USER  COMMANDS 


CSH(l) 


NAME 

csh  —  a  shell  (command  interpreter)  with  C-like  syntax 
SYNOPSIS 

csh  I  — cefinstvVxX  ]  |  arg  ...  ) 

DESCRIPTION 

Csh  is  a  command  language  interpreter  which  may  be  used  instead  of  sA(l),  typically  to  take 
advantage  of  its  history  mechanism  (see  History  Substitutions)  and  its  job  control  facilities  (see 
Jobs). 

An  instance  of  esh  begins  by  executing  commands  from  the  file  .cshrc  in  the  user’s  home  direc¬ 
tory.  If  this  is  a  login  shell  then  esh  also  executes  commands  from  the  file  .login  in  the  user’s 
home  directory.  It  is  typical  for  users  on  crt’s  to  put  the  command  atty  crt  in  their  .login 
file,  and  call  <se<(l)  from  the  .login  file  as  well. 

In  the  normal  case,  the  shell  then  begins  reading  commands  from  the  terminal,  prompting  with 
*%  ’.  Processing  of  arguments  and  the  use  of  the  shell  to  process  files  containing  command 
scripts  is  described  later. 

The  shell  then  repeatedly  performs  the  following  actions:  a  line  of  command  input  is  read  and 
broken  into  words.  This  sequence  of  words  is  placed  on  the  command  history  list  and  then 
parsed.  Finally  each  command  in  the  current  line  is  executed. 

When  a  login  shell  terminates  it  executes  commands  from  the  file  .logout  in  the  users  home  direc¬ 
tory. 

Lexical  structure 

The  shell  splits  input  lines  into  words  at  blanks  and  tabs  with  the  following  exceptions:  The  char¬ 
acters  ‘I’,  '<’,  ‘>’,  *(’,  and  ’)’  form  separate  words.  If  doubled  in  *&&’,  ‘|  ]’,  *«’,  or  '»’ 

these  pairs  form  single  words.  These  parser  metacharacters  may  be  made  part  of  other  words,  or 
prevented  their  special  meaning,  by  preceding  them  with  ‘\’.  A  newline  preceded  by  a  ‘V  is 
equivalent  to  a  blank. 

In  addition  strings  enclosed  in  matched  pairs  of  quotations,  ‘'’or  ‘  ’,  form  parts  of  a  word; 
metacharacters  in  these  strings,  including  blanks  and  tabs,  do  not  form  separate  words.  These 
quotations  have  semantics  to  be  described  subsequently.  Within  pairs  of  ‘  ’  or  ‘  ’  characters  a 
newline  preceded  by  a  ‘\’  gives  a  true  newline  character. 

When  the  shell’s  input  is  not  a  terminal,  the  character  *#’  introduces  a  comment  which  continues 
to  the  end  of  the  input  line.  The  '#’  character  does  not  introduce  a  comment  when  preceded  by 
‘\’  and  in  quotations  using  *'  ’,  and 

Commands 

A  simple  command  is  a  sequence  of  words,  the  first  of  which  specifies  the  command  to  be  exe¬ 
cuted. 

A  simple  command  or  a  sequence  of  simple  commands  separated  by  (vertical  bar)  characters 
forms  a  pipeline.  The  output  of  each  command  in  a  pipeline  is  connected  to  the  input  of  the 
next.  Sequences  of  pipelines  may  be  separated  by  and  are  then  executed  sequentially.  A 
sequence  of  pipelines  may  be  executed  without  immediately  waiting  for  it  to  terminate  by  follow¬ 
ing  it  with  an 

Any  of  the  above  may  be  placed  in  ‘(’  *)’  to  form  a  simple  command  (which  may  be  a  component 
of  a  pipeline,  etc.)  It  is  also  possible  to  separate  pipelines  with  ‘j  j’  or  *&&’  indicating,  as  in  the  C 
language,  that  the  second  is  to  be  executed  only  if  the  first  fails  or  succeeds  respectively.  (See 
Expressions). 
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Jobs 

The  shell  associates  a  job  with  each  pipeline.  It  keeps  a  table  of  current  jobs,  which  you  can 
display  with  the  jobs  command,  and  assigns  them  small  integer  numbers.  When  a  job  is  started 
asynchronously  with  *&*,  the  shell  prints  a  line  which  looks  like: 

[1]  1234 

indicating  that  this  job  is  job  number  1  and  has  one  (top-level)  process,  whose  process  id  is  1234. 

If  you  are  running  a  job  and  wish  to  do  something  else  you  may  hit  the  key  '"Z  (control-Z)  which 
sends  a  STOP  signal  to  the  current  job.  The  shell  then  normally  indicates  that  the  job  has  been 
'Stopped*,  and  displays  another  prompt.  You  can  then  manipulate  the  state  of  this  job,  putting 
it  in  the  background  with  the  bg  command,  or  run  some  other  commands  and  then  eventually 
bring  the  job  back  into  the  foreground  with  the  foreground  command  fg,  A  '"Z  takes  effect 
immediately  and  is  like  an  interrupt  in  that  pending  output  and  unread  input  are  discarded  when 
it  is  typed.  There  is  another  special  key  '"Y  which  does  not  generate  a  STOP  signal  until  a  pro¬ 
gram  attempts  to  read(2)  it.  This  can  usefully  be  typed  ahead  when  you  have  prepared  some 
commands  for  a  job  which  you  wish  to  stop  after  it  has  read  them, 

A  job  being  run  in  the  background  will  stop  if  it  tries  to  read  from  the  terminal.  Background 
jobs  are  normally  allowed  to  produce  output,  but  this  can  be  disabled  by  giving  the  command 
stty  tostop.  If  you  set  this  tty  option,  background  jobs  will  stop  when  they  try  to  produce  out¬ 
put  like  they  do  when  they  try  to  read  input. 

There  are  several  ways  to  refer  to  jobs  in  the  shell.  The  character  '%*  introduces  a  job  name.  If 
you  wish  to  refer  to  job  number  1,  you  can  name  it  as  Just  naming  a  job  brings  it  to  the 

foreground;  thus  is  a  synonym  for  *fg  %1\  which  brings  job  1  back  into  the  foreground. 
Similarly,  typing  '%!  &*  resumes  job  1  in  the  background.  Jobs  can  also  be  named  by  prefixes  of 
the  string  typed  in  to  start  them,  if  these  prefixes  are  unambiguous;  thus,  for  example,  '%ex’  nor¬ 
mally  restarts  a  suspended  €x{l)  job,  if  there  is  only  one  suspended  job  whose  name  begins  with 
the  string  'ex*.  It  is  also  possible  to  use  '%?string’  to  specify  a  job  whose  text  contains  if 

there  is  only  one  such  job. 

The  shell  maintains  a  notion  of  the  current  and  previous  jobs.  In  output  pertaining  to  jobs,  the 
current  job  is  marked  with  a  and  the  previous  job  with  a  The  abbreviation  refers 
to  the  current  job  and  '%— *  refers  to  the  previous  job.  For  close  analogy  with  the  syntax  of  the 
history  mechanism  (described  below),  '%%*  is  also  a  synonym  for  the  current  job. 

Status  reporting 

The  shell  learns  immediately  whenever  a  process  changes  state.  It  normally  informs  you  when¬ 
ever  a  job  becomes  blocked  so  that  no  further  progress  is  possible,  but  only  just  before  it  prints  a 
prompt.  This  is  done  so  that  it  does  not  otherwise  disturb  your  work.  If,  however,  you  set  the 
shell  variable  notify,  the  shell  will  notify  you  immediately  of  changes  of  status  in  background 
jobs.  There  is  also  a  shell  command  notify  which  marks  a  single  process  so  that  its  status 
changes  will  be  immediately  reported.  By  default  notify  marks  the  current  process;  simply  say 
‘notify*  after  starting  a  background  job  to  mark  it. 

When  you  try  to  leave  the  shell  while  jobs  are  stopped,  you  will  be  warned  that  ‘You  have 
stopped  jobs.*  You  may  use  the  jobs  command  to  see  what  they  are.  If  you  do  this  or  immedi¬ 
ately  try  to  exit  again,  the  shell  will  not  warn  you  a  second  time,  and  the  suspended  jobs  will  be 
terminated. 

Substitutions 

We  now  describe  the  various  transformations  the  shell  performs  on  the  input  in  the  order  in 
which  they  occur. 
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History  substitutions 

History  substitutions  place  words  from  previous  command  input  as  portions  of  new  commands, 
making  it  easy  to  repeat  commands,  repeat  arguments  of  a  previous  command  in  the  current 
command,  or  fix  spelling  mistakes  in  the  previous  command  with  little  typing  and  a  high  degree 
of  confidence.  History  substitutions  begin  with  the  character  *!’  and  may  begin  anywhere  in  the 
input  stream  (with  the  proviso  that  they  do  not  nest.)  This  *!’  may  be  preceded  by  an  \  to 
prevent  its  special  meaning;  for  convenience,  a  V  is  passed  unchanged  when  it  is  followed  by  a 
blank,  tab,  newline,  *=’  or  History  substitutions  also  occur  when  an  input  line  begins  with 
(circumflex)  —  this  special  abbreviation  is  described  later.  Any  input  line  which  contains  history 
substitution  is  echoed  on  the  terminal  before  it  is  executed  as  it  could  have  been  typed  without 
history  substitution. 

Commands  input  from  the  terminal  which  consist  of  one  or  more  words  are  saved  on  the  history 
list,  the  size  of  which  is  controlled  by  the  history  variable;  the  previous  command  is  always 
retained,  regardless  of  its  value.  The  history  substitutions  reintroduce  sequences  of  words  from 
these  saved  commands  into  the  input  stream.  Commands  are  numbered  sequentially  from  1. 

For  definiteness,  consider  the  following  output  from  the  history  command: 

9  write  michael 

10  ex  write. c 

11  cat  oldwrite.c 

12  diff  ♦write. c 

The  commands  are  shown  with  their  event  numbers.  It  is  not  usually  necessary  to  use  event 
numbers,  but  the  current  event  number  can  be  made  part  of  the  prompt  by  placing  an  T  in  the 
prompt  string. 

With  the  current  event  13  we  can  refer  to  previous  events  by  event  number  ‘!ir,  relatively  as  in 
(referring  to  the  same  event),  by  a  prefix  of  a  command  word  as  in  ‘!d’  for  event  12  or  ‘!wri’ 
for  event  9,  or  by  a  string  contained  in  a  word  in  the  command  as  in  ‘!?mic?’  also  referring  to 
event  9.  These  forms,  without  further  modification,  simply  reintroduce  the  words  of  the  specified 
events,  each  separated  by  a  single  blank.  As  a  special  case  '!!’  refers  to  the  previous  command; 
thus  ‘!!^  alone  is  essentially  a  redo. 

To  select  words  from  an  event  we  can  follow  the  event  specification  by  a  and  a  designator  for 
the  desired  words.  The  words  of  an  input  line  are  numbered  from  0,  the  first  (usually  command) 
word  being  0,  the  second  word  (first  argument)  being  1,  etc.  The  basic  word  designators  are: 

#  the  entire  command  line  typed  so  far 

0  first  (command)  word 

n  n'th  argument 

"  first  argument,  that  is,  ‘T 

$  last  argument  i 

%  word  matched  by  (immediately  preceding)  search 
z—y  range  of  words 

—y  abbreviates  *0— y’ 

♦  abbreviates  or  nothing  if  only  1  word  in  event 

X*  abbreviates  ‘z— $* 

2—  like  but  omitting  word  *$* 

The  separating  the  event  specification  from  the  word  designator  can  be  omitted  if  the  argu¬ 
ment  selector  begins  with  a  V  or  *%\  After  the  optional  word  designator  can  be 

placed  a  sequence  of  modifiers,  each  preceded  by  a  The  following  modifiers  are  defined: 

h  Remove  a  trailing  pathname  component,  leaving  the  head, 

r  Remove  a  trailing  ‘.xxx’  component,  leaving  the  root  name, 

e  Remove  all  but  the  extension  *.xxx’  part. 
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s///r/  Substitute  rfor  / 

t  Remove  all  leading  pathname  components,  leaving  the  tail. 

&  Repeat  the  previous  substitution. 

g  Apply  the  change  globally,  prefixing  the  above,  for  example,  *g&\ 

p  Print  the  new  command  but  do  not  execute  it. 

q  Quote  the  substituted  words,  preventing  further  substitutions. 

X  Like  q,  but  break  into  words  at  blanks,  tabs  and  newlines. 

Unless  preceded  by  a  ‘g*  the  modification  is  applied  only  to  the  first  modifiable  word.  With  sub¬ 
stitutions,  it  is  an  error  for  no  word  to  be  applicable. 

The  left  hand  side  of  substitutions  are  not  regular  expressions  in  the  sense  of  the  editors,  but 
rather  strings.  Any  character  may  be  used  as  the  delimiter  in  place  of  7*;  a  \  quotes  the  delim¬ 
iter  into  the  I  and  r  strings.  The  character  in  the  right  hand  side  is  replaced  by  the  text  from 
the  left.  A  \  quotes  also.  A  null  I  uses  the  previous  string  either  from  a  I  or  from  a  contex¬ 
tual  scan  string  s  in  The  trailing  delimiter  in  the  substitution  may  be  omitted  if  a  newline 

follows  immediately  as  may  the  trailing  'V  in  a  contextual  scan. 

A  history  reference  may  be  given  without  an  event  specification,  for  example,  In  this  case 
the  reference  is  to  the  previous  command  unless  a  previous  history  reference  occurred  on  the 
same  line  in  which  case  this  form  repeats  the  previous  reference.  Thus  *!?foo?"  !$’  gives  the  first 
and  last  arguments  from  the  command  matching  ‘?foo?’. 

A  special  abbreviation  of  a  history  reference  occurs  when  the  first  non-blank  character  of  an 
input  line  is  a  This  is  equivalent  to  ‘!:s"’  providing  a  convenient  shorthand  for  substitutions 
on  the  text  of  the  previous  line.  Thus  ‘"Ib'lib’  fixes  the  spelling  of  Mib*  in  the  previous  command. 
Finally,  a  history  substitution  may  be  surrounded  with  *{*  and  if  necessary  to  insulate  it  from 
the  characters  which  follow.  Thus,  after  %  —Id  "pauF  we  might  do  1{l}a*  to  do  ‘Is  —Id  "paula’, 
while  '!la’  would  look  for  a  command  starting  Ma\ 

Quotations  with  '  and  * 

The  quotation  of  strings  by  and  can  be  used  to  prevent  all  or  some  of  the  remaining  substi¬ 
tutions.  Strings  enclosed  in  are  prevented  any  further  interpretation.  Strings  enclosed  in 
are  yet  variable  and  command  expanded  as  described  below. 

In  both  cases  the  resulting  text  becomes  (all  or  part  of)  a  single  word;  only  in  one  special  case  (see 
Command  Substitition  below)  does  a  quoted  string  yield  parts  of  more  than  one  word; 
quoted  strings  never  do. 

Alias  substitution 

The  shell  maintains  a  list  of  aliases  which  can  be  established,  displayed  and  modified  by  the  alias 
and  unalias  commands.  After  a  command  line  is  scanned,  it  is  parsed  into  distinct  commands 
and  the  first  word  of  each  command,  left-to-right,  is  checked  to  see  if  it  has  an  alias.  If  it  does, 
the  text  which  is  the  alias  for  that  command  is  reread  with  the  history  mechanism  available  as 
though  that  command  were  the  previous  input  line.  The  resulting  words  replace  the  command 
and  argument  list.  If  no  reference  is  made  to  the  history  list,  the  argument  list  is  left  unchanged. 

Thus  if  the  alias  for  is*  is  is  —I*  the  command  is  /usr’  would  map  to  is  —1  /usr*,  the  argument 
list  here  being  undisturbed.  Similarly  if  the  alias  for  iookup*  was  ‘grep  !"  /etc/passwd*,  iookup 
bill’  would  map  to  ‘grep  bill  /etc/passwd’. 

If  an  alias  is  found,  the  word  transformation  of  the  input  text  is  performed  and  the  aliasing  pro¬ 
cess  begins  again  on  the  reformed  input  line.  Looping  is  prevented  if  the  first  word  of  the  new 
text  is  the  same  as  the  old  by  flagging  it  to  prevent  further  aliasing.  Other  loops  arc  detected 
and  cause  an  error. 

Note  that  the  mechanism  allows  aliases  to  introduce  parser  metasyntax.  Thus  we  can  ‘alias  print 
^pr  \!^  j  Ipr'’  to  make  a  command  which  pr^s  its  arguments  to  the  line  printer. 
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Variable  substitution 

The  shell  maintains  a  set  of  variables,  each  of  which  has  as  value  a  list  of  zero  or  more  words. 
Some  of  these  variables  are  set  by  the  shell  or  referred  to  by  it.  For  instance,  the  argv  variable  is 
an  image  of  the  shell’s  argument  list,  and  words  of  this  variable’s  value  are  referred  to  in  special 
ways. 

Values  of  variables  may  be  displayed  and  changed  by  using  the  set  and  unset  commands.  Of  the 
variables  referred  to  by  the  shell  a  number  are  toggles;  the  shell  does  not  care  what  their  value 
is,  only  whether  they  are  set  or  not.  For  instance,  the  verbose  variable  is  a  toggle  which  causes 
command  input  to  be  echoed.  The  setting  of  this  variable  results  from  the  — v  command  line 
option. 

Other  operations  treat  variables  numerically.  The  command  permits  numeric  calculations  to 
be  performed  and  the  result  assigned  to  a  variable.  Variable  values  are,  however,  always 
represented  as  (zero  or  more)  strings.  For  the  purposes  of  numeric  operations,  the  null  string  is 
considered  to  be  zero,  and  the  second  and  subsequent  words  of  multiword  values  are  ignored. 

After  the  input  line  is  aliased  and  parsed,  and  before  each  command  is  executed,  variable  substi¬ 
tution  is  performed  keyed  by  characters.  This  expansion  can  be  prevented  by  preceding  the 
*$’  with  a  except  within  ‘"’s  where  it  always  occurs,  and  within  where  it  never  occurs. 
Strings  quoted  by  ’  are  interpreted  later  (see  Command  substitution  below)  so  *$’  substitution 
does  not  occur  there  until  later,  if  at  all.  A  *$’  is  passed  unchanged  if  followed  by  a  blank,  tab,  or 
end-oMine. 

Input/output  redirections  are  recognized  before  variable  expansion,  and  are  variable  expanded 
separately.  Otherwise,  the  command  name  and  entire  argument  list  are  expanded  together.  It  is 
thus  possible  for  the  first  (command)  word  to  this  point  to  generate  more  than  one  word,  the 
first  of  which  becomes  the  command  name,  and  the  rest  of  which  become  arguments. 

Unless  enclosed  in  or  given  the  ‘:q’  modifier  the  results  of  variable  substitution  may  eventually 
be  command  and  filename  substituted.  Within  a  variable  whose  value  consists  of  multiple 
words  expands  to  a  (portion  of)  a  single  word,  with  the  words  of  the  variables  value  separated  by 
blanks.  When  the  ‘:q’  modifier  is  applied  to  a  substitution  the  variable  expands  to  multiple 
words  with  each  word  separated  by  a  blank  and  quoted  to  prevent  later  command  or  filename 
substitution. 

The  following  metasequences  are  provided  for  introducing  variable  values  into  the  shell  input. 
Except  as  noted,  it  Is  an  error  to  reference  a  variable  which  is  not  set. 

$name 

${name} 

Are  replaced  by  the  words  of  the  value  of  variable  name,  each  separated  by  a  blank. 
Braces  insulate  name  from  following  characters  which  would  otherwise  be  part  of  it.  Shell 
variables  have  names  consisting  of  up  to  20  letters  and  digits  starting  with  a  letter.  The 
underscore  character  is  considered  a  letter. 

If  name  is  not  a  shell  variable,  but  is  set  in  the  environment,  that  value  is  returned  (but  : 
modifiers  and  the  other  forms  given  below  are  not  available  in  this  case). 

Sname  [selector] 

${name|selector]} 

May  be  used  to  select  only  some  of  the  words  from  the  value  of  name.  The  selector  is  sub¬ 
jected  to  substitution  and  may  consist  of  a  single  number  or  two  numbers  separated  by  a 
The  first  word  of  a  variables  value  is  numbered  ‘1*.  If  the  first  number  of  a  range  is 
omitted  it  defaults  to  ‘T.  If  the  last  member  of  a  range  is  omitted  it  defaults  to  *$#name’. 
The  selector  selects  all  words.  It  is  not  an  error  for  a  range  to  be  empty  if  the  second 
argument  is  omitted  or  in  range. 
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$#name 

${#name} 

Gives  the  number  of  words  in  the  variable.  This  is  useful  for  later  use  in  a  *[se!ector|*, 

$0 

Substitutes  the  name  of  the  file  from  which  command  input  is  being  read.  An  error  occurs 
if  the  name  is  not  known. 

$number 

${number} 

Equivalent  to  '$argv [number]'. 

$♦ 

Equivalent  to  ‘$argv[*p. 

The  modifiers  ‘:h',  ‘:t',  ‘:r\  *:q’  and  ‘:x'  may  be  applied  to  the  substitutions  above  as  may  *:gh', 
':gt’  and  ':gr\  If  braces  *{’  appear  in  the  command  form  then  the  modifiers  must  appear 
within  the  braces. 

The  current  implementation  allows  only  one  modifier  on  each  expansion. 

The  following  substitutions  may  not  be  modified  with  modifiers. 

$?name 

${?name} 

Substitutes  the  string  ‘1'  if  name  is  set,  ‘0’  if  it  is  not. 

$?0 

Substitutes  ‘1’  if  the  current  input  filename  is  known,  ‘0’  if  it  is  not. 

$$ 

Substitute  the  (decimal)  process  number  of  the  (parent)  shell. 

$< 

Substitutes  a  line  from  the  standard  input,  with  no  further  interpretation  thereafter.  It  can 
be  used  to  read  from  the  keyboard  in  a  shell  script. 

Command  and  filename  subBtltutlon 

The  remaining  substitutions,  command  and  filename  substitution,  are  applied  selectively  to  the 
arguments  of  builtin  commands.  This  means  that  portions  of  expressions  which  are  not 
evaluated  are  not  subjected  to  these  expansions.  For  commands  which  are  not  internal  to  the 
shell,  the  command  name  is  substituted  separately  from  the  argument  list.  This  occurs  very  late, 
after  input-output  redirection  is  performed,  and  in  a  child  of  the  main  shell. 

Command  substitution 

Command  substitution  is  indicated  by  a  command  enclosed  in  ’.  The  output  from  such  a  com¬ 
mand  is  normally  broken  into  separate  words  at  blanks,  tabs  and  newlines,  with  null  words  being 
discarded,  this  text  then  replacing  the  original  string.  Within  ‘"'s,  only  newlines  force  new  words; 
blanks  and  tabs  are  preserved. 

In  any  case,  the  single  final  newline  does  not  force  a  new  word.  Note  that  it  is  thus  possible  for  a 
command  substitution  to  yield  only  part  of  a  word,  even  if  the  command  outputs  a  complete  line. 

Filename  substitution 

If  a  word  contains  any  of  the  characters  *('  or  *{'  or  begins  with  the  character  that 

word  is  a  candidate  for  filename  substitution,  also  known  as  ‘globbing’.  This  word  is  then 
regarded  as  a  pattern,  and  replaced  with  an  alphabetically  sorted  list  of  file  names  which  match 
the  pattern.  In  a  list  of  words  specifying  filename  substitution  it  is  an  error  for  no  pattern  to 
match  an  existing  file  name,  but  it  is  not  required  for  each  pattern  to  match.  Only  the  meta¬ 
characters  'V  and  imply  pattern  matching,  the  characters  and  *{'  being  more  akin  to 
abbreviations. 
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In  matching  filenames,  the  character  at  the  beginning  of  a  filename  or  immediately  following  a 
7’,  as  well  as  the  character  7’  must  be  matched  explicitly.  The  character  *♦’  matches  any  string 
of  characters,  including  the  null  string.  The  character  'V  matches  any  single  character.  The 
sequence  matches  any  one  of  the  characters  enclosed.  Within  a  pair  of  characters 
separated  by  ’  matches  any  character  lexically  between  the  two. 

The  character  at  the  beginning  of  a  filename  is  used  to  refer  to  home  directories.  Standing 
alone  —  that  is,  —  it  expands  to  the  invoker’s  home  directory  as  reflected  in  the  value  of  the 
variable  home.  When  followed  by  a  name  consisting  of  letters,  digits  and  ’  characters  the  shell 
searches  for  a  user  with  that  name  and  substitutes  their  home  directory;  thus  ‘~ken’  might 
expand  to  7^sr/ken’  and  ‘''ken/chmach’  to  7^sr/ken/chmach’.  If  the  character  is  followed 
by  a  character  other  than  a  letter  or  7*  n.ppcars  not  at  the  beginning  of  a  word,  it  is  left 
undisturbed. 

The  metanotation  *a{b,c,d}e’  is  a  shorthand  for  ‘abe  ace  ade’.  Left  to  right  order  is  preserved, 
with  results  of  matches  being  sorted  separately  at  a  low  level  to  preserve  this  order.  This  con¬ 
struct  may  be  nested.  Thus  ‘"'source/sl/{oldls,ls}.c’  expands  to  7^sr/source/sl/oldls,c 
/usr/source/sl/ls.c’  whether  or  not  these  files  exist  without  any  chance  of  error  if  the  home 
directory  for  ‘source’  is  7«sr /source’.  Similarly  ‘../{memo, ♦box}’  might  expand  to  ‘../memo 
../box  .y^fibox’.  (Note  that  ‘memo’  was  not  sorted  with  the  results  of  matching  ‘*box’.)  As  a  spe¬ 
cial  case  ‘}’  and  ‘{}’  are  passed  undisturbed. 

Input/output 

The  standard  input  and  standard  output  of  a  command  may  be  redirected  with  the  following 
syntax: 

<  name 

Open  file  name  (which  is  first  variable,  command  and  filename  expanded)  as  the  standard 
input. 

«  word 

Read  the  shell  input  up  to  a  line  which  is  identical  to  word.  Word  is  not  subjected  to  vari¬ 
able,  filename  or  command  substitution,  and  each  input  line  is  compared  to  word  before  any 
substitutions  are  done  on  this  input  line.  Unless  a  quoting  or  ’  appears  in  word 

variable  and  command  substitution  is  performed  on  the  intervening  lines,  allowing  to 
quote  ‘$’,  ‘V  and  ’.  Commands  which  are  substituted  have  all  blanks,  tabs,  and  newlines 
preserved,  except  for  the  final  newline  which  is  dropped.  The  resultant  text  is  placed  in  an 
anonymous  temporary  file  which  is  given  to  the  command  as  standard  input. 

>  name 
>!  name 
>&  name 
>&!  name 

The  file  name  is  used  as  standard  output.  If  the  file  does  not  exist,  it  is  created.  If  the  file 
exists,  it  is  truncated;  its  previous  contents  are  lost. 

If  the  variable  noctobber  is  set,  the  file  must  not  exist  or  be  a  character  special  file  (for 
example,  a  terminal  or  ‘/dev/null’)  or  an  error  results.  This  helps  prevent  accidental  des¬ 
truction  of  files.  In  this  case  the  ‘!’  forms  can  be  used  and  suppress  this  check. 

The  forms  Involving  route  the  diagnostic  output  into  the  specified  file  as  well  as  the 
standard  output.  Name  is  expanded  in  the  same  way  as  ‘<’  input  filenames  are. 

»  name 
»&  name 
»!  name 
»&!  name 

Uses  file  name  as  standard  output  like  ‘>’  but  places  output  at  the  end  of  the  file.  If  the 
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variable  no  clobber  is  set,  it  is  an  error  for  the  file  not  to  exist  unless  one  of  the  forms  is 
given.  Otherwise  similar  to 

A  command  receives  the  environment  in  which  the  shell  was  invoked  as  modified  by  the  input- 
output  parameters  and  the  presence  of  the  command  in  a  pipeline.  Thus,  unlike  some  previous 
shells,  commands  run  from  a  file  of  shell  commands  have  no  access  to  the  text  of  the  commands 
by  default;  rather  they  receive  the  original  standard  input  of  the  shell.  The  *«'  mechanism 
should  be  used  to  present  inline  data.  This  permits  shell  command  scripts  to  function  as  com¬ 
ponents  of  pipelines  and  allows  the  shell  to  block  read  its  input.  Note  that  the  default  standard 
input  for  a  command  run  detached  is  not  modified  to  be  the  empty  file  ‘/dev/nulF;  rather  the 
standard  input  remains  as  the  original  standard  input  of  the  shell.  If  this  is  a  terminal  and  if  the 
process  attempts  to  read  from  the  terminal,  the  process  blocks  and  the  user  is  notified  (see  Jobs 
above.) 

Diagnostic  output  may  be  directed  through  a  pipe  with  the  standard  output.  Simply  use  the 
form  rather  than  just 


Expressions 


A  number  of  the  builtin  commands  (to  be  described  subsequently)  take  expressions,  in  which  the 
operators  are  similar  to  those  of  C,  with  the  same  precedence.  These  expressions  appear  in  the 
exit,  if,  and  while  commands.  The  following  operators  are  available: 

j  j  &&  j  !=  «~  !"  <=  >=  <  >  «  »  -h  -  *  /  %  !  ^  (  ) 

Here  the  precedence  increases  to  the  right,  '==  *!=’  and  *<=*  *>=’  and  *«’ 
and  and  and  being,  in  groups,  at  the  same  level.  The  '==’  and 

operators  compare  their  arguments  as  strings;  all  others  operate  on  numbers.  The  operators 
and  V*  are  like  and  *!=’  except  that  the  right  hand  side  is  a  pattern  (containing,  for 
example,  **’s,  and  instances  of  ‘[— 10  against  which  the  left  hand  operand  is  matched.  This 
reduces  the  need  for  use  of  the  switch  statement  in  shell  scripts  when  all  that  is  really  needed  is 
pattern  matching. 


Strings  which  begin  with  ‘0*  are  considered  octal  numbers.  Null  or  missing  arguments  are  con¬ 
sidered  ‘O’.  The  result  of  all  expressions  are  strings,  which  represent  decimal  numbers.  It  is 
important  to  note  that  no  two  components  of  an  expression  can  appear  in  the  same  word;  except 
when  adjacent  to  components  of  expressions  which  are  syntactically  significant  to  the  parser  (*&* 
should  be  surrounded  by  spaces.  Variables  whose  names  appear  in  expres¬ 
sions  must  have  their  names  preceded  by  a  dollar  ($)  sign,  for  example: 


@  grab  ^  $grab+2 

Also  available  in  expressions  as  primitive  operands  are  command  executions  enclosed  in  and 
and  file  enquiries  of  the  form  f  name’  where  /  is  one  of: 


r  read  access 

w  write  access 

x  execute  access 

e  existence 

o  ownership 

z  zero  size 

f  plain  file 

d  directory 

The  specified  name  is  command  and  filename  expanded  and  then  tested  to  see  if  it  has  the 
specified  relationship  to  the  real  user.  If  the  file  does  not  exist  or  is  inaccessible  then  all  enquiries 
return  false,  that  is,  ‘O’.  Command  executions  succeed,  returning  true,  that  is,  *1*,  if  the  com¬ 
mand  exits  with  status  0,  otherwise  they  fail,  returning  false,  that  is,  ‘O’.  If  more  detailed  status 
information  is  required,  the  command  should  be  executed  outside  of  an  expression  and  the  vari¬ 
able  status  examined. 
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Control  flow 

The  shell  contains  a  number  of  commands  which  can  be  used  to  regulate  the  flow  of  control  in 
command  files  (shell  scripts)  and  (in  limited  but  useful  ways)  from  terminal  input.  These  com¬ 
mands  all  operate  by  forcing  the  shell  to  reread  or  skip  in  its  input  and,  due  to  the  implementa¬ 
tion,  restrict  the  placement  of  some  of  the  commands. 

The  foreachf  $witck,  and  while  statements,  as  well  as  the  if— then— else  form  of  the  if  statement 
require  that  the  major  keywords  appear  in  a  single  simple  command  on  an  input  line  as  shown 
below. 

If  the  shell’s  input  is  not  seekable,  the  shell  buffers  up  input  whenever  a  loop  is  being  read  and 
performs  seeks  in  this  internal  buffer  to  accomplish  the  rereading  implied  by  the  loop.  (To  the 
extent  that  this  allows,  backward  goto’s  will  succeed  on  non-seekable  inputs.) 

Builtln  commands 

Builtin  commands  are  executed  within  the  shell.  If  a  builtin  command  occurs  as  any  component 
of  a  pipeline  except  the  last,  it  is  executed  in  a  subshell. 

alias 

alias  name 
alias  name  wordlist 

The  first  form  prints  all  aliases.  The  second  form  prints  the  alias  for  name.  The  final  form 
assigns  the  specified  wordliet  as  the  alias  of  name;  wordlidt  is  command  and  filename  substi¬ 
tuted.  Name  is  not  allowed  to  be  alias  or  unalias.  Putting  single  quote  signs  (apostrophes) 
around  wordlist  and  placing  a  \  character  in  front  of  any  signs  in  wordlist  often  solves 
any  obscure  problems  with  aliases. 

alloc 

Shows  the  amount  of  dynamic  core  in  use,  broken  down  into  used  and  free  core,  and 
address  of  the  last  location  in  the  heap.  With  an  argument  shows  each  used  and  free  block 
on  the  internal  dynamic  memory  chain  indicating  its  address,  size,  and  whether  it  is  used  or 
free.  This  is  a  debugging  command  and  may  not  work  in  production  versions  of  the  shell;  it 
requires  a  modified  version  of  the  system  memory  allocator. 

bg 

bg  %job  ... 

Puts  the  current  or  specified  jobs  into  the  background,  continuing  them  if  they  were 
stopped. 

break 

Resumes  execution  after  the  end  of  the  nearest  enclosing  foreach  or  while.  The  remaining 
commands  on  the  current  line  are  executed.  Multi-level  breaks  are  thus  possible  by  writing 
them  all  on  one  line. 

breaksw 

Breaks  from  a  switch^  resuming  after  the  endsw, 
case  label: 

A  label  in  a  switch  statement  as  discussed  below. 

cd 

cd  name 

chdir 

chdir  name 

Change  the  shell’s  working  directory  to  directory  name.  If  no  argument  is  given,  change  to 
the  home  directory  of  the  user. 

If  name  is  not  found  as  a  subdirectory  of  the  current  directory  (and  does  not  begin  with 
*./’  or  component  of  the  variable  cdpath  is  checked  to  see  if  it  has  a  subdirectory 

name.  Finally,  if  all  else  fails  but  name  is  a  shell  variable  whose  value  begins  with  */’,  this 
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is  tried  to  see  if  it  is  a  directory. 

continue 

Continue  execution  of  the  nearest  enclosing  while  or  foreach.  The  rest  of  the  commands  on 
the  current  line  are  executed. 

default: 

Labels  the  default  case  in  a  ewitck  statement.  The  default  should  come  after  all  case  labels. 

dirs 

Prints  the  directory  stack;  the  top  of  the  stack  is  at  the  left,  the  first  directory  in  the  stack 
being  the  current  directory. 

echo  wordlist 
echo  — n  wordlist 

The  specified  words  are  written  to  the  shelPs  standard  output,  separated  by  spaces,  and 
terminated  with  a  newline  unless  the  — n  option  is  specified. 

else 

end 

endif 

endsw 

See  the  description  of  the  foreach,  if,  switch,  and  while  statements  below. 

eva!  arg  ... 

(As  in  5A(1).)  The  arguments  are  read  as  input  to  the  shell  and  the  resulting  command(s) 
executed.  This  is  usually  used  to  execute  commands  generated  as  the  result  of  command  or 
variable  substitution,  since  parsing  occurs  before  these  substitutions.  See  for  an 

example  of  using  evai 

exec  command 

The  specified  command  is  executed  in  place  of  the  current  shell. 

exit 

exit(expr) 

The  shell  exits  either  with  the  value  of  the  status  variable  (first  form)  or  with  the  value  of 
the  specified  expr  (second  form). 

fg  %joh  ... 

Brings  the  current  or  specified  jobs  into  the  foreground,  continuing  them  if  they  were 
stopped. 

foreach  name  (wordlist) 

end 

The  variable  name  is  successively  set  to  each  member  of  wordlist  and  the  sequence  of  com¬ 
mands  between  this  command  and  the  matching  end  are  executed.  (Both  foreach  and  end 
must  appear  alone  on  separate  lines.) 

The  builtin  command  continue  may  be  used  to  continue  the  loop  prematurely  and  the  buil- 
tin  command  break  to  terminate  it  prematurely.  When  this  command  is  read  from  the  ter¬ 
minal,  the  loop  is  read  up  once  prompting  with  before  any  statements  in  the  loop  are 
executed.  If  you  make  a  mistake  typing  in  a  loop  at  the  terminal  you  can  rub  it  out. 

glob  wordlist 

Like  echo  but  no  \  escapes  are  recognized  and  words  are  delimited  by  null  characters  in 
the  output.  Useful  for  programs  which  wish  to  use  the  shell  to  filename  expand  a  list  of 
words. 
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goto  word 

The  specified  word  is  filename  and  command  expanded  to  yield  a  string  of  the  form  ‘label** 
The  shell  rewinds  its  input  as  much  as  possible  and  searches  for  a  line  of  the  form  iabel:’ 
possibly  preceded  by  blanks  or  tabs.  Execution  continues  after  the  specified  line. 

hashstat 

Print  a  statistics  line  indicating  how  effective  the  internal  hash  table  has  been  at  locating 
commands  (and  avoiding  ezec*8).  An  exec  is  attempted  for  each  component  of  the  path 
where  the  hash  function  indicates  a  possible  hit,  and  in  each  component  which  does  not 
begin  with  a  7’. 

htatory 
history  n 
history  — r  n 
history  — h  n 

Displays  the  history  event  list;  if  n  is  given,  display  only  the  n  most  recent  events.  The  —r 
option  reverses  the  order  of  printout  to  be  most  recent  first  rather  than  oldest  first.  The 
— h  option  means  display  the  history  list  without  leading  numbers.  This  is  used  to  produce 
files  suitable  for  sourceing  using  the  — h  option  to  source, 

if  (expr)  command 

If  the  specified  expression  evaluates  true,  the  single  command  with  arguments  is  executed. 
Variable  substitution  on  command  happens  early,  at  the  same  time  it  does  for  the  rest  of 
the  if  command.  Command  must  be  a  simple  command,  not  a  pipeline,  a  command  list,  or 
a  parenthesized  command  list.  Input/output  redirection  occurs  even  if  expr  is  false,  when 
command  is  not  executed  (this  is  a  bug). 

if  (expr)  then 
else  if  (expr2)  then 
else 
endif 

If  the  specified  expr  is  true,  the  commands  to  the  first  else  are  executed;  else  if  €xpr2  is 
true,  the  commands  to  the  second  else  are  executed,  etc.  Any  number  of  else-if  pairs  are 
possible;  only  one  endif  is  needed.  The  else  part  is  likewise  optional.  (The  words  else  and 
endif  must  appear  at  the  beginning  of  input  lines;  the  if  must  appear  alone  on  its  input  line 
or  after  an  else,) 

Jobs 
jobs  ~1 

Lists  the  active  jobs;  given  the  —1  options  lists  process  id’s  in  addition  to  the  normal  infor¬ 
mation. 

kill  %job 
kill  — sig  %job  ... 

kill  pid 

kill  —sig  pid  ... 

kill  -1 

Sends  either  the  TERM  (terminate)  signal  or  the  specified  signal  to  the  specified  jobs  or 
processes.  Signals  are  either  given  by  number  or  by  names  (as  given  in 
f  usrf  include/ signal.h,  stripped  of  the  prefix  “SIG”).  The  signal  names  are  listed  by  “kill 
—1”,  There  is  no  default,  saying  just  ‘kill’  does  not  send  a  signal  to  the  current  job.  If  the 
signal  being  sent  is  TERM  (terminate)  or  HUP  (hangup),  then  the  job  or  process  is  sent  a 
CONT  (continue)  signal  as  well. 
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limit 

limit  resource 

limit  resource  maximum-use 

Limits  the  consumption  by  the  current  process  and  each  process  it  creates  to  not  individu¬ 
ally  exceed  maximum-use  on  the  specified  resource.  If  no  maximum-use  is  given,  the 
current  limit  is  printed;  if  no  resource  is  given,  all  limitations  are  given. 

Resources  controllable  currently  include  cpuiime  (the  maximum  number  of  cpu-seconds  to 
be  used  by  each  process),  filesize  (the  largest  single  file  which  can  be  created),  datasize  (the 
maximum  growth  of  the  data+stack  region  via  shrk{2)  beyond  the  end  of  the  program 
text),  stacksize  (the  maximum  size  of  the  automatically-extended  stack  region),  and 
coredumpsize  (the  size  of  the  largest  core  dump  that  will  be  created). 

The  maximum-use  may  be  given  as  a  (floating  point  or  integer)  number  followed  by  a  scale 
factor.  For  all  limits  other  than  cputime  the  default  scale  is  ‘k’  or  'kilobytes’  (1024  bytes);  a 
scale  factor  of  'm’  or  ‘megabytes’  may  also  be  used.  For  cputime  the  default  scaling  is 
‘seconds’,  while  ‘m’  for  minutes  or  *h’  for  hours,  or  a  time  of  the  form  ‘mm:ss’  giving 
minutes  and  seconds  may  be  used. 

For  both  resource  names  and  scale  factors,  unambiguous  prefixes  of  the  names  suffice. 

login 

Terminate  a  login  shell,  replacing  it  with  an  instance  of  /bin/Iogln.  This  is  one  way  to  log 
off,  included  for  compatibility  with  sh{l). 

logout 

Terminate  a  login  shell.  Especially  useful  if  ignoreeof  is  set. 

nice 

nice  -bnumber 
nice  command 
nice  +number  command 

The  first  form  sets  the  nice  for  this  shell  to  4.  The  second  form  sets  the  nice  to  the  given 
number.  The  final  two  forms  run  command  at  priority  4  and  number  respectively.  The 
super-user  may  specify  negative  niceness  by  using  ‘nice  —number  ...’.  Command  is  always 
executed  in  a  sub-shell,  and  the  restrictions  placed  on  commands  in  simple  if  statements 
apply. 

nohup 

nohup  command 

The  first  form  can  be  used  in  shell  scripts  to  cause  hangups  to  be  ignored  for  the  remainder 
of  the  script.  The  second  form  runs  the  specified  command  with  hangups  ignored.  All 
processes  detached  with  are  effectively  nohup*ed. 

notify 

notify  %job  ... 

Notify  the  user  asynchronously  when  the  status  of  the  current  or  specified  jobs  changes; 
normally  notification  is  presented  before  a  prompt.  This  is  automatic  if  the  shell  variable 
notify  is  set. 

onintr 
onintr  — 
onintr  label 

Control  the  action  of  the  shell  on  interrupts.  The  first  form  restores  the  default  action  of 
the  shell  on  interrupts  (terminates  shell  scripts  and  returns  to  the  terminal  command  input 
level).  The  second  form  ‘onintr  — ’  ignores  all  interrupts.  The  final  form  makes  the  shell 
execute  a  ‘goto  label’  when  an  interrupt  is  received  or  a  child  process  terminates  because  it 
was  interrupted. 
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In  any  case,  if  the  shell  is  running  detached  and  interrupts  are  being  ignored,  all  forms  of 
onm^r  have  no  meaning  and  interrupts  continue  to  be  ignored  by  the  shell  and  all  invoked 
commands. 

popd 
popd  d-n 

Pops  the  directory  stack,  returning  to  the  new  top  directory.  With  an  argument  ‘-Hn’  dis¬ 
cards  the  nth  entry  in  the  stack.  The  elements  of  the  directory  stack  are  numbered  from  0 
starting  at  the  top. 

pushd 
pushd  name 
pushd  +n 

With  no  arguments,  pushd  exchanges  the  top  two  elements  of  the  directory  stack.  Given  a 
name  argument,  pushd  changes  to  the  new  directory  (as  in  cd)  and  pushes  the  old  current 
working  directory  (as  in  esw)  onto  the  directory  stack.  With  a  numeric  argument,  rotates 
the  nth  argument  of  the  directory  stack  around  to  be  the  top  element  and  changes  to  it. 
The  members  of  the  directory  stack  are  numbered  from  the  top  starting  at  0. 

rehash 

Recompute  the  internal  hash  table  of  the  contents  of  the  directories  in  the  path  variable. 
This  is  needed  if  new  commands  are  added  to  directories  in  the  path  while  you  are  logged 
in.  This  should  only  be  necessary  if  you  add  commands  to  one  of  your  own  directories,  or  if 
a  systems  programmer  changes  the  contents  of  one  of  the  system  directories. 

repeat  count  command 

The  specified  command  which  is  subject  to  the  same  restrictions  as  the  command  in  the  one 
line  if  statement  above,  is  executed  count  times.  I/O  redirections  occur  exactly  once,  even 
if  count  is  0. 


set 

set  name 
set  name  =  word 
set  name[index]=word 
set  name=(wordlist) 

The  first  form  of  the  command  shows  the  value  of  all  shell  variables.  Variables  which  have 
other  than  a  single  word  as  value  print  as  a  parenthesized  word  list.  The  second  form  sets 
name  to  the  null  string.  The  third  form  sets  name  to  the  single  word.  The  fourth  form 
sets  the  indexHh  component  of  name  to  word;  this  component  must  already  exist.  The  final 
form  sets  name  to  the  list  of  words  in  wordlisL  In  all  cases  the  value  is  command  and 
filename  expanded. 

These  arguments  may  be  repeated  to  set  multiple  values  in  a  single  set  command.  Note 
however,  that  variable  expansion  happens  for  all  arguments  before  any  setting  occurs. 

setenv  name  value 

Sets  the  value  of  environment  variable  name  to  be  value,  a  single  string.  The  most  com¬ 
monly  used  environment  variables,  USER,  TERM,  and  PATH,  are  automatically  imported 
to  and  exported  from  the  csb  variables  user,  term,  and  path;  there  is  no  need  to  use  setenv 
for  these. 


Bhift 

shift  variable 

The  members  of  argv  are  shifted  to  the  left,  discarding  argvflj.  It  is  an  error  for  argv  not 
to  be  set  or  to  have  less  than  one  word  as  value.  The  second  form  performs  the  same  func¬ 
tion  on  the  specified  variable. 
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source  name 
source  — h  name 

The  shell  reads  commands  from  name.  Source  commands  may  be  nested;  if  they  are  nested 
too  deeply  the  shell  may  run  out  of  file  descriptors.  An  error  in  a  source  at  any  level  ter¬ 
minates  all  nested  source  commands.  Normally,  input  during  source  commands  is  not 
placed  on  the  history  list;  the  — h  option  places  the  commands  in  the  history  list  without 
being  executed, 

stop 

stop  %job  ... 

Stops  the  current  or  specified  job  which  is  executing  in  the  background. 

suspend 

Stops  the  shell  in  its  tracks,  much  as  if  it  had  been  sent  a  stop  signal  with  ^Z.  This  is  most 
often  used  to  stop  shells  started  by  s«(l). 

switch  (string) 
case  strl: 

breaksw 

default: 

breaksw 

endsw 

Each  case  label  is  successively  matched,  against  the  specified  siring  which  is  first  command 
and  filename  expanded.  The  file  metacharacters  V,  and  may  be  used  in  the  case 
labels,  which  are  variable  expanded.  If  none  of  the  labels  match  before  a  ‘default’  label  is 
found,  execution  begins  after  the  default  label.  Each  case  label  and  the  default  label  must 
appear  at  the  beginning  of  a  line.  The  command  breaksw  continues  execution  after  the 
endsw.  Otherwise  control  may  fall  through  case  labels  and  default  labels  as  in  C.  If  no 
label  matches  and  there  is  no  default,  execution  continues  after  the  endsw. 

time 

time  command 

With  no  argument,  a  summary  of  time  used  by  this  shell  and  its  children  is  printed.  If 
arguments  are  given  the  specified  simple  command  is  timed  and  a  time  summary  as 
described  under  the  time  variable  is  printed.  If  necessary,  an  extra  shell  is  created  to  print 
the  time  statistic  when  the  command  completes. 

umask 
umask  value 

The  file  creation  mask  is  displayed  (first  form)  or  set  to  the  specified  value  (second  form). 
The  mask  is  given  in  octal.  Common  values  for  the  mask  are  002  giving  all  access  to  the 
group  and  read  and  execute  access  to  others  or  022  giving  all  access  except  no  write  access 
for  users  in  the  group  or  others. 

unallas  pattern 

All  aliases  whose  names  match  the  specified  pattern  are  discarded.  Thus  all  aliases  are 
removed  by  ‘unalias  It  is  not  an  error  for  nothing  to  be  unaliased. 

unhash 

Use  of  the  internal  hash  table  to  speed  location  of  executed  programs  is  disabled. 

unliinU  resource 
unllmlt 

Removes  the  limitation  on  resource.  If  no  resource  is  specified,  all  resource  limitations  are 
removed. 
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unset  pattern 

All  variables  whose  names  match  the  specified  pattern  are  removed.  Thus  all  variables  are 
removed  by  ‘unset  this  has  noticeably  distasteful  side-effects.  It  Is  not  an  error  for  noth¬ 
ing  to  be  unset. 

unsetenv  pattern 

Removes  all  variables  whose  name  match  the  specified  pattern  from  the  environment.  See 
also  the  setenv  command  above  and  pr»nfeni?(l). 

wait 

All  background  jobs  are  waited  for.  It  the  shell  is  interactive,  an  interrupt  can  disrupt  the 
wait,  at  which  time  the  shell  prints  names  and  Job  numbers  of  all  jobs  known  to  be  out¬ 
standing. 

while  (expr) 
end 

While  the  specified  expression  evaluates  non-zero,  the  commands  between  the  while  and  the 
matching  end  are  evaluated.  Break  and  continue  may  be  used  to  terminate  or  continue  the 
loop  prematurely.  (The  while  and  end  must  appear  alone  on  their  input  lines.)  Prompting 
occurs  here  the  first  time  through  the  loop  as  for  the  foreach  statement  if  the  source  of 
input  is  a  terminal. 

%job 

Brings  the  specified  job  into  the  foreground. 

%job  & 

Continues  the  specified  job  in  the  background. 

@ 

@  name  =  expr 
@  namejindex]  =  expr 

The  first  form  prints  the  values  of  all  the  shell  variables.  The  second  form  sets  the 
specified  name  to  the  value  of  expr.  If  the  expression  contains  *<’,  *>’,  or  ‘|’  then  at 
least  this  part  of  the  expression  must  be  placed  within  ‘(’  *)’.  The  third  form  assigns  the 
value  of  expr  to  the  index'th  argument  of  name.  Both  name  and  its  index’th  component 
must  already  exist. 

The  operators  ‘-b-’,  etc  are  available  as  in  C.  The  space  separating  the  name  from 
the  assignment  operator  is  optional.  Spaces  are,  however,  mandatory  in  separating  com¬ 
ponents  of  expr  which  would  otherwise  be  single  words. 

Special  postfix  ‘-b+’  and  ‘ — ’  operators  increment  and  decrement  name  respectively,  that 
is,  i++’. 

Note  that  there  must  be  a  space  after  the  sign. 

Pre-defined  and  environment  variables 

The  following  variables  have  special  meaning  to  the  shell.  Of  these,  argv,  cwd,  home,  path, 
prompt,  shell  and  status  are  always  set  by  the  shell.  Except  for  cwd  and  status  this  setting  occurs 
only  at  initialization;  these  variables  will  not  then  be  modified  unless  this  is  done  explicitly  by  the 
user. 

This  shell  copies  the  environment  variable  USER  into  the  variable  user,  TERM  into  term,  and 
HOME  into  home,  and  copies  these  back  into  the  environment  whenever  the  normal  shell  vari¬ 
ables  are  reset.  The  environment  variable  PATH  is  similarly  handled;  it  is  only  necessary  to 
worry  about  its  setting  in  the  file  .cshrc,  as  inferior  csh  processes  will  import  the  definition  of 
path  from  the  environment,  and  re-export  it  if  you  then  change  it.  It  could  be  set  once  in  the 
.login  except  that  commands  through  the  network  would  not  see  the  definition. 
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argv 

cdpath 

cwd 

echo 

histchars 

history 

home 

ignoreeof 

mail 


noclobber 

noglob 

nonomatch 

notify 

path 


Set  to  the  arguments  to  the  shell.  Positional  parameters  are  substituted  from 
this  variable:  ‘$1’  is  replaced  by  ‘$argY[lj*,  etc. 

Gives  a  list  of  alternate  directories  searched  to  find  subdirectories  in  chdir  com¬ 
mands. 

The  full  pathname  of  the  current  directory. 

Set  when  the  — x  command  line  option  is  given.  Echoes  each  command  and  its 
arguments  just  before  execution.  For  non-builtin  commands  all  expansions  occur 
before  echoing.  Builtin  commands  are  echoed  before  command  and  filename 
substitution,  since  these  substitutions  are  then  done  selectively. 

Can  be  given  a  string  value  to  change  the  characters  used  in  history  substitu¬ 
tion.  The  first  character  of  its  value  is  used  as  the  history  substitution  charac¬ 
ter,  replacing  the  default  character  !.  The  second  character  of  its  value  replaces 
the  character  f  in  quick  substitutions. 

Can  be  given  a  numeric  value  to  control  the  size  of  the  history  list.  Any  com¬ 
mand  which  has  been  referenced  in  this  many  events  will  not  be  discarded.  If 
you  use  an  overly-large  value  for  history,  the  shell  may  run  out  of  memory.  The 
last  executed  command  is  always  saved  on  the  history  list. 

The  home  directory  of  the  invoker,  initialized  from  the  environment.  The 
filename  expansion  of  refers  to  this  variable. 

If  set,  the  shell  ignores  end-of-file  signals  from  terminals.  This  prevents  shells 
from  being  accidentally  killed  by  controI-D^s. 

The  files  where  the  shell  checks  for  mail.  This  is  done  after  each  command  com¬ 
pletion  which  will  result  in  a  prompt,  if  a  specified  interval  has  elapsed.  The 
shell  says  ‘You  have  new  mail’  if  the  file  exists  with  an  access  time  not  greater 
than  its  modify  time. 

If  the  first  word  of  the  value  of  mail  is  numeric  it  specifies  a  different  mail 
checking  interval,  in  seconds,  than  the  default,  which  is  5  minutes. 

If  multiple  mail  files  are  specified,  the  shell  says  ‘New  mail  in  name'  when  there 
is  mail  in  the  file  name. 

As  described  in  the  section  on  Input/ output,  restrictions  are  placed  on  output 
redirection  to  insure  that  files  are  not  accidentally  destroyed,  and  that  *»’ 
redirections  refer  to  existing  files. 

If  set,  filename  expansion  is  inhibited.  This  is  most  useful  in  shell  scripts  which 
are  not  dealing  with  filenames,  or  after  a  list  of  filenames  has  been  obtained  and 
further  expansions  are  not  desirable. 

If  set,  it  is  not  an  error  for  a  filename  expansion  to  not  match  any  existing  files; 
rather  the  primitive  pattern  is  returned.  It  is  still  an  error  for  the  primitive  pat¬ 
tern  to  be  malformed,  that  is,  ‘echo  [’  still  gives  an  error. 

If  set,  the  shell  notifies  asynchronously  of  job  completions.  The  default  is  to 
rather  present  job  completions  just  before  printing  a  prompt. 

Each  word  of  the  path  variable  specifies  a  directory  in  which  commands  are  to 
be  sought  for  execution.  A  null  word  specifies  the  current  directory.  If  there  is 
no  path  variable,  only  full  path  names  will  execute.  The  usual  search  path  is 
‘/bin’  and  ‘/usr/bin’,  but  this  may  vary  from  system  to  system.  For  the  super- 
user  the  default  search  path  is  ‘/etc’,  ‘/bin’  and  ‘/usr/bin’.  A  shell  which  is 
given  neither  the  — c  nor  the  — t  option  will  normally  hash  the  contents  of  the 
directories  in  the  path  variable  after  reading  ,cshrc,  and  each  time  the  path 
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prompt 


savehist 


shell 


status 


time 


variable  is  reset.  If  new  commands  are  added  to  these  directories  while  the  shell 
is  active,  it  may  be  necessary  to  give  the  rehash  or  the  commands  may  not  be 
found. 

The  string  which  is  printed  before  each  command  is  read  from  an  interactive 
terminal  input.  If  a  *!*  appears  in  the  string  it  is  replaced  by  the  current  event 
number  unless  a  preceding  ‘V  given.  Default  is  or  *#  ’  for  the  super- 
user.  / 

is  given  a  numeric  value  to  control  the  number  of  entries  of  the  history  list  that 
are  saved  in  "'/.history  when  the  user  logs  out.  Any  command  which  has  been 
referenced  in  this  many  events  will  be  saved.  During  start  up  the  shell  sources 
"'/.history  into  the  history  list  enabling  history  to  be  saved  across  logins. 
Overly-large  values  of  savehist  will  slow  down  the  shell  during  start  up. 

The  file  in  which  the  shell  resides.  This  is  used  in  forking  shells  to  interpret  files 
which  have  execute  bits  set,  but  which  are  not  executable  by  the  system.  (See 
the  description  of  Non-builtin  Command  Execution  below.)  Initialized  to  the 
(system-dependent)  home  of  the  shell. 

The  status  returned  by  the  last  command.  If  it  terminated  abnormally,  then 
0200  is  added  to  the  status.  Builtin  commands  which  fail  return  exit  status  ‘1’, 
all  other  builtin  commands  set  status  '0\ 

Controls  automatic  timing  of  commands.  The  time  variable  can  be  supplied 
with  one  or  two  values,  such  as  ‘set  time=3’  or  ‘set  time=(3  %P%”)^  The 
first  value  is  a  number  —  n  for  instance.  The  shell  displays  a  resource-usage 
summary  for  any  command  running  for  more  than  n  CPU  seconds.  The  second 
value  is  optional  and  is  a  character  string  which  determines  which  resources  the 
user  wishes  displayed.  The  character  string  can  be  any  string  of  text  with 
embedded  control  key-letters  in  it.  A  control  key-letter  is  a  percent  sign  (%) 
followed  by  a  single  upper-case  letter.  To  print  a  percent  sign,  use  two  percent 
signs  in  a  row.  Unrecognized  key-letters  are  simply  printed.  The  control  key- 
letters  are: 

D  Average  amount  of  unshared  data  space  used  in  Kilobytes. 

E  Elapsed  (wallclock)  time  for  the  command. 

F  Page  faults. 

I  Number  of  block  input  operations. 

K  Average  amount  of  unshared  stack  space  used  in  Kilobytes. 

M  Maximum  real  memory  used  during  execution  of  the  process. 

O  Number  of  block  output  operations. 

P  Total  CPU  time  —  U  (user)  plus  S  (system)  —  as  a  percentage  of  E 
(elapsed)  time. 

S  Number  of  seconds  of  CPU  time  consumed  by  the  kernel  on  behalf  of 
the  user^s  process. 

U  Number  of  seconds  of  CPU  time  devoted  to  the  user's  process. 

W  Number  of  swaps. 

X  Average  amount  of  shared  memory  used  in  Kilobytes. 

The  default  resource- usage  summary  is  a  line  of  the  form: 

uuu.uu  88e,es  ee:ee  pp%  xxx-i-dddk  Ui-k-ooolo  mmmpfH-u;«;w 

where  uuu.ti  is  the  user  time  (U),  m.a  is  the  system  time  (S),  ee:ee  is  the 
elapsed  time  (E),  pp  is  the  percentage  of  CPU  time  versus  elapsed  time  (P),  xxx 
is  the  average  shared  memory  in  Kilobytes  (X),  ddd  is  the  average  unshared  data 
space  in  Kilobytes  (D),  in  and  ooo  are  the  number  of  block  input  and  output 
operations  respectively  (I  and  O),  mmm  is  the  number  of  page  faults  (F),  and  ww 
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is  the  number  of  swaps  (W)* 

verbose  Set  by  the  — v  command  line  option,  displays  the  words  of  each  command  after 

history  substitution. 

Non-builtin  command  execution 

When  a  command  to  be  executed  is  found  to  not  be  a  builtin  command  the  shell  attempts  to  exe¬ 
cute  the  command  via  ezecve{2y  Each  word  in  the  variable  path  names  a  directory  from  which 
the  shell  will  attempt  to  execute  the  command.  If  it  is  given  neither  a  — c  nor  a  — t  option,  the 
shell  hashes  the  names  in  these  directories  into  an  internal  table  so  that  it  will  only  try  an  exec  in 
a  directory  if  there  is  a  possibility  that  the  command  resides  there.  This  greatly  speeds  com¬ 
mand  location  when  a  large  number  of  directories  are  present  in  the  search  path.  If  this  mechan¬ 
ism  has  been  turned  off  (via  unhash),  or  if  the  shell  was  given  a  — c  or  — t  argument,  and  in  any 
case  for  each  directory  component  of  path  which  does  not  begin  with  a  the  shell  concatenates 
with  the  given  command  name  to  form  a  path  name  of  a  file  which  it  then  attempts  to  execute. 

Parenthesized  commands  are  always  executed  in  a  subshell.  Thus  ‘(cd  ;  pwd)  ;  pwd'  prints  the 
home  directory;  leaving  you  where  you  were  (printing  this  after  the  home  directory),  while  *cd  ; 
pwd'  leaves  you  in  the  home  directory.  Parenthesized  commands  are  most  often  used  to  prevent 
ckdir  from  affecting  the  current  shell. 

If  the  file  has  execute  permissions  but  is  not  an  executable  binary  to  the  system,  it  is  assumed  to 
be  a  file  containing  shell  commands  and  a  new  shell  is  spawned  to  read  it. 

If  there  is  an  alias  for  shell  then  the  words  of  the  alias  are  prepended  to  the  argument  list  to 
form  the  shell  command.  The  first  word  of  the  alias  should  be  the  full  path  name  of  the  shell 
(for  example,  ‘$sheir).  Note  that  this  is  a  special,  late  occurring,  case  of  alias  substitution,  and 
only  allows  words  to  be  prepended  to  the  argument  list  without  modification. 

Argument  list  processing 

If  argument  0  to  the  shell  is  '  then  this  is  a  login  shell.  The  flag  arguments  are  interpreted  as 
follows: 

— c  Commands  are  read  from  the  (single)  following  argument  which  must  be  present.  Any 
remaining  arguments  are  placed  in  argv. 

—e  The  shell  exits  if  any  invoked  command  terminates  abnormally  or  yields  a  non-zero  exit 
status. 

— f  The  shell  will  start  faster,  because  it  will  neither  search  for  nor  execute  commands  from  the 
file  ‘.eshre’  in  the  invokers  home  directory. 

—I  The  shell  is  interactive  and  prompts  for  its  top-level  input,  even  if  it  appears  to  not  be  a 
terminal.  Shells  are  interactive  without  this  option  if  their  inputs  and  outputs  are  termi¬ 
nals. 

— n  Commands  are  parsed,  but  not  executed.  This  may  aid  in  syntactic  checking  of  shell 
scripts. 

•-8  Command  input  is  taken  from  the  standard  input. 

— t  A  single  line  of  input  is  read  and  executed.  A  ‘V  ^sed  to  escape  the  newline  at  the 

end  of  this  line  and  continue  onto  another  line. 

— V  Sets  the  verbose  variable,  so  that  command  input  is  echoed  after  history  substitution. 

“X  Sets  the  echo  variable,  so  that  commands  are  echoed  immediately  before  execution. 

— V  Sets  the  verbose  variable  even  before  ‘.eshre’  is  executed. 

— X  Is  to  —X  as  —V  is  to  — v. 
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After  processing  of  flag  arguments  If  arguments  remain  but  none  of  the  — c,  —1,  — s,  or  — t 
options  was  given  the  first  argument  is  taken  as  the  name  of  a  file  of  commands  to  be  executed. 
The  shell  opens  this  file,  and  saves  its  name  for  possible  resubstitution  by  ‘$0’.  Since  many  sys¬ 
tems  use  either  the  standard  version  6  or  version  7  shells  whose  shell  scripts  are  not  compatible 
with  this  shell,  the  shell  will  execute  such  a  ‘standard*  shell  if  the  first  character  of  a  script  is  not 
a  '#*,  that  is,  if  the  script  does  not  start  with  a  comment.  Remaining  arguments  initialize  the 
variable  argv. 

Signal  handling 

The  shell  normally  ignores  quit  signals.  Jobs  running  detached  (either  by  *&*  or  the  bg  or  & 
commands)  are  immur48  to  signals  generated  from  the  keyboard,  including  hangups.  Other  sig¬ 
nals  have  the  values  which  the  shell  inherited  from  its  parent.  The  shell’s  handling  of  interrupts 
and  terminate  signals  in  shell  scripts  can  be  controlled  by  onintr.  Login  shells  catch  the  icr^ 
minate  signal;  otherwise  this  signal  is  passed  on  to  children  from  the  state  in  the  shell’s  parent. 
In  no  case  are  interrupts  allowed  when  a  login  shell  is  reading  the  file  ‘.logout’. 

Read  at  beginning  of  execution  by  each  shell. 

Read  by  login  shell,  after  ‘.cshrc’  at  login. 

Read  by  login  shell,  at  logout. 

Saved  history  for  use  at  next  login. 

Standard  shell,  for  shell  scripts  not  starting  with  a  *#’. 

Temporary  file  for  ‘«’. 

Source  of  home  directories  for  ‘“'name’. 

Words  can  be  no  longer  than  1024  characters.  The  system  limits  argument  lists  to  10240  charac¬ 
ters.  The  number  of  arguments  to  a  command  which  involves  filename  expansion  is  limited  to 
l/6*th  the  number  of  characters  allowed  in  an  argument  list.  Command  substitutions  may  sub¬ 
stitute  no  more  characters  than  are  allowed  in  an  argument  list.  To  detect  looping,  the  shell  res¬ 
tricts  the  number  of  alias  substititutions  on  a  single  line  to  20. 

SEE  ALSO 

sh(l),  access(2),  execYe(2),  fork(2),  killpg(2),  pipe(2),  umask(2),  getrlimit(2),  setrlimit(2),  sigvec(2), 
wait(2),  tty(4),  a.out(5),  environ(6),  Using  the  C-Shell  in  the  Beginner's  Guide  to  the  Sun  Works¬ 
tation 

BUGS 

When  a  command  is  restarted  from  a  stop,  the  shell  prints  the  directory  it  started  in  if  this  is 
different  from  the  current  directory;  this  can  be  misleading  (that  is,  wrong)  as  the  job  may  have 
changed  directories  internally. 

Shell  builtin  functions  are  not  stoppable/restartable.  Command  sequences  of  the  form  ‘a  ;  b  ;  c* 
are  also  not  handled  gracefully  when  stopping  is  attempted.  If  you  suspend  ‘b’,  the  shell  will  then 
immediately  execute  ‘c*.  This  is  especially  noticeable  if  this  expansion  results  from  an  alias.  It 
suffices  to  place  the  sequence  of  commands  in  ()’s  to  force  it  to  a  subshell,  that  is,  (  a  ;  b  ;  c  ) . 

Control  over  tty  output  after  processes  are  started  is  primitive;  perhaps  this  will  inspire  someone 
to  work  on  a  good  virtual  terminal  interface.  In  a  virtual  terminal  interface  much  more  interest¬ 
ing  things  could  be  done  with  output  control. 

Alias  substitution  is  most  often  used  to  clumsily  simulate  shell  procedures;  shell  procedures 
should  be  provided  rather  than  aliases. 

Commands  within  loops,  prompted  for  by  ‘?*,  are  not  placed  in  the  history  list.  Control  structure 
should  be  parsed  rather  than  being  recognized  as  built-in  commands.  This  would  allow  control 
commands  to  be  placed  anywhere,  to  be  combined  with  and  to  be  used  with  &  and  ; 
metasyntax. 


FILES 

"'/.cshrc 

"/.login 

“/.logout 

“/.history 

/bin/sh 

/tmp/sh* 

/etc/passwd 

LIMITATIONS 
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It  should  be  possible  to  use  the  modifiers  on  the  output  of  command  substitutions.  There  are 
two  problems  with  modifier  usage  on  substitutions:  not  all  of  the  modifiers  are  available; 
only  one  modifier  per  command  substitution  is  allowed. 

Quoting  conventions  are  contradictory  and  confusing. 

Symbolic  links  fool  the  shell.  In  particular,  dire  and  *cd  don’t  work  properly  once  you’ve 
crossed  through  a  symbolic  link. 

set  path  should  remove  duplicate  pathnames  from  the  pathname  list.  These  often  occur 
because  a  shell  script  or  a  ,C8hrc  file  does  something  like 
set  path  ==(/u8r /local  /usr/hosts  $path)  to  ensure  that  the  named  directories  are  in  the 
pathname  list. 

There  is  no  way  to  direct  error  output  to  one  place  and  standard  output  to  another  place,  except 
by  invoking  a  sub-shell  as  follows: 

tutorial%  (  command  >  outfile)  >Sc  errorfile 
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NAME 

ctags  —  create  a  tags  file 
SYNOPSIS 

ctaga  I  — BFatuwvx  ]  file 
DESCRIPTION 

Ciags  makes  a  tags  file  for  ej(l)  from  the  specified  C,  Pascal  and  FORTRAN  sources.  A  tags  file 
gives  the  locations  of  specified  objects  (in  this  case  functions  and  type.defs)  in  a  group  of  files. 
Each  line  of  the  tags  file  contains  the  object  name,  the  file  in  which  it  is  defined,  and  an  address 
specification  for  the  object  definition.  Functions  are  searched  with  a  pattern,  typedefs  with  a  line 
number.  Specifiers  are  given  in  separate  fields  on  the  line,  separated  by  blanks  or  tabs.  Using  the 
tags  file,  ex  can  quickly  find  these  objects  definitions. 

Files  whose  name  ends  in  or  .h  are  assumed  to  be  C  source  files  and  are  searched  for  C  routine 
and  macro  definitions.  Others  are  first  examined  to  see  if  they  contain  any  Pascal  or  FORTRAN 
routine  definitions;  if  not,  they  are  processed  again  looking  for  C  definitions. 

The  tag  main  is  treated  specially  in  C  programs.  The  tag  formed  is  created  by  prepending  M  to 
the  name  of  the  file,  with  a  trailing  ,c  removed,  if  any,  and  leading  pathname  components  also 
removed.  This  makes  use  of  ctags  practical  in  directories  with  more  than  one  program. 

OPTIONS 

““X 

-F 
-B 
—a 
-t 
—w 
— u 

FILES 

tags 

SEE  ALSO 

ex(l},  vi(l) 

BUGS 

Recognition  of  functions,  subroutines  and  procedures  for  FORTRAN  and  Pascal  is  done  is  a 
very  simpleminded  way.  No  attempt  is  made  to  deal  with  block  structure;  if  you  have  two  Pas¬ 
cal  procedures  in  different  blocks  with  the  same  name  you  lose. 

Does  not  know  about  #ifdefs. 


produce  a  list  of  object  names,  the  line  number  and  file  name  on  which  each  is  defined,  as 
well  as  the  text  of  that  line  and  prints  this  on  the  standard  output.  This  is  a  simple 
index  which  can  be  printed  out  as  an  off-line  readable  function  index. 

use  forward  searching  patterns  (/.../)  (default). 

use  backward  searching  patterns  (?...?). 

append  to  tags  file. 

create  tags  for  typedefs. 

suppress  warning  diagnostics. 

update  the  specified  files  in  tags,  that  is,  all  references  to  them  are  deleted,  and  the  new 
values  are  appended  to  the  file.  Beware:  this  option  is  implemented  in  a  way  which  is 
rather  slow;  it  is  usually  faster  to  simply  rebuild  the  tags  file. 

output  tags  file 
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NAME 

date  —  display  or  set  the  date^ 

SYNOPSIS 

date  I  — u  1  [  yymmddhhmm  |  -ss  |  | 

DESCRIPTION 

Date  displays  the  current  date  and  time  when  used  without  an  argument. 

Only  the  super-user  may  set  the  date,  yy  is  the  last  two  digits  of  the  year;  the  first  mm  is  the 
month  number;  dd  is  the  day  number  in  the  month;  hh  is  the  hour  number  (24  hour  system);  the 
second  mm  is  the  minute  number;  (optional)  specifies  seconds.  The  year,  month  and  day  may 
be  omitted;  the  current  values  are  supplied  as  defaults. 

OPTIONS 

— u  Display  the  date  in  GMT  (universal  time).  The  system  operates  in  GMT;  date  normally 
takes  care  of  the  conversion  to  and  from  local  standard  and  daylight  time.  — u  may  also 
be  used  to  set  GMT  time. 

EXAMPLE 

date  10080045 

sets  the  date  to  Oct  8,  12:45  AM. 

FILES 

/usr/adm/wtmp  to  record  time-setting 

SEE  ALSO 

utmp(5) 

DIAGNOSTICS 

‘Failed  to  set  date:  Not  owner’  if  you  try  to  change  the  date  but  are  not  the  super-user. 
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NAME 

dbx  “  debugger 
SYNOPSIS 

dbx  [  —r  I  [  — 1  1  [  — I  dir  \  [  ohjfile  [  corefile  ]] 

DESCRIPTION 

Dbx  is  a  tool  for  source-level  debugging  and  execution  of  programs.  It  accepts  the  same  com¬ 
mands  as  dbxtool  (1),  but  provides  a  user  interface  which  does  not  use  the  window  system. 

Objfile  is  an  object  file  produced  by  cc(l),  f77{l)  and  pc(l)  (or  a  combination  of  them)  with  the 
appropriate  flag  (—g)  specified  to  produce  symbol  information  in  the  object  file.  IMPORTANT: 
every  stage  of  the  compilation  process,  including  the  Id  phase,  must  include  the  —g  option. 

If  no  objfile  is  specified,  one  uses  the  debug  command  to  specify  the  program  to  be  debugged. 
The  object  file  contains  a  symbol  table  which  includes  the  names  of  all  the  source  files  translated 
by  the  compiler  to  create  it.  These  files  are  available  for  perusal  while  using  the  debugger. 

If  a  file  named  core  exists  in  the  current  directory  or  a  corefile  is  specified,  dbx  can  be  used  to 
examine  the  state  of  the  program  when  it  faulted. 

Debugger  commands  in  the  file  ,dbxinit  are  executed  immediately  after  the  symbolic  information 
is  read,  if  that  file  exists  in  the  current  directory,  or  in  the  user’s  home  directory  if  .dbxinit 
doesn’t  exist  in  the  current  directory. 

OPTIONS 

— r  Execute  objfile  immediately.  Parameters  follow  the  object  file  name  (redirection  is  han¬ 

dled  properly).  If  the  program  terminates  successfully,  dbx  exits.  Otherwise,  dbx  reports 
the  reason  for  termination  and  waits  for  user  response.  Dbx  reads  from  /dev/ tty  when 
— p  is  specified  and  standard  input  is  not  a  terminal. 

—I  Force  dbx  to  act  as  though  standard  input  is  a  terminal. 

—I  dir  Add  dir  to  the  list  of  directories  that  are  searched  when  looking  for  a  source  file.  Nor¬ 
mally  dbx  looks  for  source  files  in  the  current  directory  and  in  the  directory  where  objfile 
is  located.  The  directory  search  path  can  also  be  set  with  the  use  command. 

DBX  AND  DBXTOOL  COMMON  USER  INTERFACE 

The  following  material  concerning  the  user  interface  applies  to  both  dbx  and  dbxtool.  Note  that 
commands,  toolenv,  button,  and  unbutton  affect  only  dbxtool;  they  are  described  in  the 
dbxtool  (1)  manual  entry.  The  commands  described  below  are  divided  into  the  following 
categories: 

Execution  and  Tracing 

Run  the  program  being  debugged,  trace  its  execution,  and  stop  at  selected  places. 
Displaying  and  Naming  Data 

Display  data  and  locate  variables  in  the  debugged  program. 

Accessing  Source  Files 

Provide  operations  (such  as  editing)  on  the  actual  source  text  of  the  program. 

Machine  Level  Commands 

Provide  access  to  memory  locations  and  machine  registers. 

Miscellaneous 

Miscellaneous  commands  such  as  help,  and  call  a  shell. 

The  most  useful  basic  commands  to  know  about  are  run  to  run  the  program  being  debugged, 
where  to  obtain  a  stack  trace  with  line  numbers,  print  for  displaying  variables,  and  stop  for 
setting  breakpoints. 
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File  Names 

File  names  within  dbx  may  include  shell  metacharacters.  The  shell  used  for  pattern  matching  is 
determined  by  the  SHELL  environment  variable. 


Expressions 

Dbx  Expressions  are  combinations  of  variables,  constants,  procedure  calls,  and  operators.  Hexa¬ 
decimal  constants  must  be  preceded  by  a  ‘Ox’  and  octal  constants  by  a  ‘O’.  Character  constants 
must  be  enclosed  in  single  quotes.  Expressions  cannot  involve  strings,  structures,  or  arrays, 
although  elements  of  structures  or  arrays  may  be  used. 

Dbx  recognizes  these  operators: 

■+  —  *  /  div  % 

add,  subtract,  multiply,  divide,  integer  divide  and  remainder 

<<  >>  &  I 

left  shift,  right  shift,  bitwise  and,  bitwise  or,  and  bitwise  complement 

&  * 

address  of  operator  and  contents  of  operator 
<><=>=  ==  !=  1 

less  than,  greater  than,  less  than  or  equal,  greater  than  or  equal,  equal  to,  not  equal  to,  and 
not 

&&  j| 

logical  and,  and  logical  or 
sizeof  (cast) 

sizeof  variable  or  type,  and  type  cast 

The  field  reference  operator  (‘.’)  can  be  used  with  pointers  to  records,  as  well  as  records,  making 
the  C  operator  ‘— >’  unnecessary  (although  it  is  supported). 

Precedence  and  associativity  of  operators  are  the  same  as  in  C.  Parentheses  can  be  used  for 
grouping. 

Of  course,  if  the  program  being  debugged  is  not  active  and  there  is  no  core  file,  one  may  only  use 
expressions  containing  constants.  Procedure  calls  require  an  active  child  process. 

Dbx  and  FORTRAN 

Note  the  following  when  using  dbx  with  FORTRAN  programs: 

1.  Array  elements  must  be  referenced  with  square  brackets  ‘j’  and  *]’  rather  than 
parentheses,  e.g.,  print  whatslijS]  instead  of  print  whatslt(3). 

2.  The  main  routine  is  referenced  as  MAIN  (as  distinguished  from  ‘main’).  All  other  names 
in  the  source  file  which  have  upper  case  letters  in  them  will  be  lower  case  in  dbx,  unless 
the  — U  option  of  f77  is  used  to  compile  the  program. 

3.  When  referring  to  the  value  of  a  logical  type  in  an  expression,  use  the  value  0  or  1  rather 
than  false  or  true,  respectively. 

Dbx  Scope  Rule* 

Dbx  has  two  external  variables  which  it  uses  to  resolve  scope  conflicts.  These  are  called  ‘file’  and 
‘func’  —  see  Section  3  below.  Accessing  Source  Files.  The  values  of  ‘file’  and  ‘func’  change 
automatically  as  files  and  routines  are  entered  and  exited  during  execution  of  the  user  program. 
‘File’  and  ‘func’  can  also  be  changed  by  the  user.  Changing  ‘func’  also  changes  the  value  of  ‘file’; 
however,  changing  ‘file’  does  not  change  ‘func’. 
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‘Func’  is  used  for  name  resolution,  as  in  the  command;  print  grab  where  grab  may  be  defined 
in  two  different  routines.  The  search  order  is: 

1.  Search  for  ‘grab’  in  the  routine  named  by  ‘func’, 

2.  If  ‘grab’  doesn’t  exist  in  the  routine  named  by  ‘func’,  the  file  containing  the  routine  named 
by  ‘func’  is  searched, 

3.  finally  the  next  outer  level  —  the  whole  program  in  the  case  of  C  and  FORTRAN  —  is 
searched  for  ‘grab’. 

Clearly,  if  ‘grab’  is  local  to  a  different  routine  than  the  one  named  by  ‘func’,  or  is  a  static  vari¬ 
able  in  a  different  file  than  is  the  routine  named  by  ‘func’,  it  won’t  be  found.  Note,  however, 
that  print  a.grab  is  allowed,  as  long  as  routine  ‘a’  has  been  entered  but  not  exited  yet.  Note 
that  the  file  that  routine  ‘a’  is  in  might  have  to  be  specified  when  the  file  name  (minus  its  suffix) 
is  the  same  as  a  routine  name.  For  example,  if  routine  ‘a’  is  found  in  module  ‘a.c’,  then 
print  a.grab  would  be  not  enough  —  one  would  have  to  use  print  a.a.grab.  If  in  doubt  as  to 
how  to  specify  a  name,  use  the  whereis  command,  as  in  wherels  grab  to  display  the  full 
qualifications  of  all  instances  of  the  specified  name  (grab  in  this  case). 

‘File’  is  used  to: 

1.  resolve  conflicts  when  setting  ‘func’  —  for  example,  when  a  C  program  has  two  static  rou¬ 
tines  with  the  same  name, 

2.  determine  which  file  to  use  for  commands  which  take  only  a  source  line  number  —  for  exam¬ 
ple,  stop  at  55,  and: 

3.  determine  which  file  to  use  for  commands  such  as  the  ‘edit’  command  which  has  optional 
arguments  or  no  arguments  at  all. 

When  dhx  begins  execution,  the  value  of  ‘file’  is  the  first  source  file  in  the  compiler/load  list  and 
the  value  of  ‘func’  is  the  module  for  this  same  file  (that  is,  without  the  suffix  ‘•c’,  ‘•f’  or  ‘•p’). 
This  causes  name  resolution  to  take  place  on  a  global  level,  that  is,  names  are  resolved  such  that 
the  most  global  element  is  found.  After  execution  begins,  however,  ‘func’  always  has  a  value 
corresponding  to  a  routine  name. 

Note  that  changing  ‘func’  doesn’t  affect  the  place  where  dhx  continues  execution  when  the  pro¬ 
gram  is  restarted. 

!•  Execution  and  Tracing  Commands 

When  the  process  being  debugged  is  executing,  it  may  be  interrupted  by  typing  the  interrupt 
character.  The  process  is  stopped  and  dhx  becomes  ready  to  accept  commands.  The  process  can 
be  continued  again  with  the  cont  command. 

run  [ar^fs]  \<^  filename]  [>^/ertame] 

Start  executing  ohjfile,  passing  arg$  as  command  line  arguments;  <  or  >  can  be  used  to 
redirect  input  or  output  in  the  usual  manner.  Otherwise,  all  characters  in  arga  are  passed 
through  unchanged.  If  no  arguments  are  specified,  the  argument  list  in  the  last  previous 
run  command  (if  any)  is  used.  If  objfile  has  been  written  since  the  last  time  the  symbolic 
information  was  read  in,  dhx  reads  in  the  new  information. 

cont  |at  source-line^numher]  [numher] 

Continue  execution  from  where  it  stopped,  or,  if  the  clause  ‘at  $ource-line-number'  is  given, 
from  that  line  number.  The  number  causes  execution  to  continue  as  if  that  signal  had 
occurred. 

Source^line-number  is  evaluated  relative  to  the  current  ’file*  and  must  be  within  the  current 
procedure/function.  Execution  cannot  be  continued  if  the  process  has  ’finished’,  i.e.,  called 
the  standard  procedure  ’_exit’.  Dbx  captures  control  when  the  process  attempts  to  exit, 
thereby  letting  the  user  examine  the  program  state. 

trace  \\n  procedure/function]  \\t  condition] 
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trace  eource-line-number  [If  condition] 
trace  procedure f function  [If  condition] 
trace  expression  st  source-line-number  [If  condition] 
tTMe  variable  [In  procedure/function]  [If  condition] 

Display  tracing  information  when  the  program  is  executed.  A  number  is  associated  with 
the  command  and  can  be  used  to  turn  the  tracing  off  (see  the  delete  command). 

If  no  argument  is  specified,  each  source  line  is  displayed  before  it  is  executed.  Execution  is 
substantially  slower  during  this  form  of  tracing. 

The  clause  In  procedure/ function"  restricts  tracing  information  to  be  displayed  only  while 
executing  inside  the  given  procedure  or  function.  Note  that  the  'procedure/ function"  traced 
must  be  visible  in  the  scope  in  which  the  trace  command  is  issued  —  see  the  'func'  com¬ 
mand. 

Condition  is  a  Boolean  expression  and  is  evaluated  prior  to  displaying  the  tracing  informa¬ 
tion;  the  information  is  displayed  only  if  condition  is  true. 

The  first  argument  describes  what  is  to  be  traced.  The  effects  of  different  kinds  of  argu¬ 
ments  are  described  below: 

Source  Line  Number 

Display  the  line  immediately  prior  to  executing  it.  Source  line  numbers  in  a  file 
other  than  the  current  one  must  be  preceded  by  the  name  of  the  file  in  quotes  and 
a  colon,  for  example,  ”mumble.p”:17. 

Procedure  or  Function  Name 

Every  time  the  procedure  or  function  is  called,  display  information  telling  what 
routine  called  it,  from  what  source  line  it  was  called,  and  what  parameters  were 
passed  to  it.  In  addition,  its  return  is  noted,  and  if  it  is  a  function,  the  return  value 
is  also  displayed. 

Expression 

If  the  argument  is  an  expression  with  an  at  clause,  the  value  of  the  expression  is 
displayed  whenever  the  identified  source  line  is  reached. 

Variable 

The  name  and  value  of  the  variable  are  displayed  whenever  the  value  changes. 
Execution  is  substantially  slower  during  this  form  of  tracing. 

Tracing  is  turned  off  whenever  the  block  in  which  it  was  turned  on  is  exited.  For  instance, 
if  the  program  is  stopped  inside  some  procedure  and  tracing  is  invoked,  the  tracing  will  end 
when  the  procedure  is  exited.  To  trace  the  whole  program,  tracing  must  be  invoked  before 
a  run  command  is  issued. 

stop  at  source-line-number  [if  condition] 
stop  in  procedure/ function  [If  condition] 
stop  variable  [It  condition] 
stop  if  condition 

Stop  execution  when  the  given  line  is  reached,  procedure  or  function  is  called,  variable  is 
changed,  or  condition  becomes  true.  Execution  slows  considerably  when  conditional  stops 
are  used,  and  is  very  slow  when  checking  for  a  change  in  a  variable. 

when  in  procedure/ function  {  command;  ...} 
when  at  source-line-number  {  command;  ...} 
when  condition  {  command;  ...} 

Execute  the  given  dbx  commands  when  the  procedure  or  function  is  called,  line  number  is 
reached,  or  condition  is  true.  The  braces  and  the  semicolon  separating  the  commands  are 
required. 

status  [  >  filename  \ 

Display  the  currently  active  trace  and  stop  commands. 
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delete  command-number  (,  command-number] 

delete  all 

Remove  the  traces  and/or  stops  corresponding  to  the  given  numbers,  or  all  of  them.  The 
status  command  displays  the  numbers  associated  with  traces  and  stops. 

clear  source-line-number 

Clears  ALL  breakpoints  at  the  given  source  line  number. 

catch  number  [,  ...  number] 

Ignore  number  [,  ...  number] 

Start  (’^catch")  or  stop  (’^ignore**)  trapping  the  signals  with  the  given  numfters  before  they 
are  sent  to  the  program  being  debugged.  This  is  useful  when  a  program  being  debugged 
handles  signals  such  as  interrupts.  Initially  all  signals  are  trapped  except  SIGHUP, 
SIGCONT,  SIGCHILD,  SIGALRM,  SIGKILL,  SIGSTP,  and  SIGWINCH. 

step  \n\ 

Execute  through  the  next  n  source  lines  and  stop  on  the  (n+i)st  such  line.  If  n  is  not 
specified,  it  is  taken  to  be  one.  Step  into  procedures  and  functions. 

next  [n| 

Execute  through  the  next  n  source  lines  and  stop  on  the  (n+/)st  such  line.  If  n  is  not 
specified,  it  is  taken  to  be  one.  Count  procedure  and  function  calls  as  single  statements. 

When  using  conditions  with  the  trace  and  stop  commands,  remember  that  variable  names  are 
resolved  with  respect  to  the  current  scope  not  the  scope  of  the  trace  or  stop  command.  For 
example,  if  you  are  currently  stopped  in  function  foo  and  you  issue  the  command  stop  in  bar  If 
X  ==  5,  the  variable  x  refers  to  x  in  function  foo  not  in  function  bar.  The  func  command  can 
be  used  to  changed  the  scope  before  issuing  a  trace  or  stop  command. 

2«  Naming,  Printing  and  Displaying  Data 
print  expression  [,  expression  ...] 

Print  the  values  of  the  expressions.  Expressions  may  involve  function  calls.  If  execution 
encounters  any  breakpoints,  execution  halts  and  the  dbx  command  level  is  re-entered,  A 
stack  trace  with  the  where  command  shows  that  the  call  originated  from  the  dbx  com¬ 
mand  level. 

Variables  having  the  same  identifier  as  one  in  the  current  block  may  be  referenced  as 
'block-name*variable\  where  block-name  is  a  unique  identifier  for  a  block.  For  example, 
to  access  variable  ‘c*  inside  routine  ‘a’  which  is  declared  inside  module  ‘a.c\  one  would 
have  to  use  print  a«a*c  to  make  the  name  'a’  unambiguous.  Use  wherels  to  determine 
the  fully  qualified  name  of  an  identifier. 

display  [  expression  [ ,  expression  . . .  |  ] 

Display  the  values  of  the  expressions  each  time  execution  of  the  program  being  debugged 
stops.  In  dbxtootf  the  expressions  and  their  values  appear  in  the  display  window.  The 
name  qualification  rules  for  print  apply  to  display  as  well.  With  no  arguments,  the 
display  command  prints  a  list  of  the  expressions  currently  being  displayed. 

undlsplay  expression  [,  expression 

Stop  displaying  the  expressions  and  their  values  each  time  execution  of  the  program 
being  debugged  stops.  The  name  qualification  rules  for  print  apply  to  undisplay  as  well. 

whatis  identifier 
whatis  type 

Print  the  declaration  of  the  given  identifier  or  type.  The  identifier  may  be  qualified  with 
block  names  as  above.  Types  are  useful  to  print  all  the  members  of  a  structure,  union, 
or  enumerated  type. 

which  identifier 
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Print  the  fully  qualified  form  of  the  given  identifier,  that  is,  the  outer  blocks  that  the 
identifier  is  associated  with. 

whereis  identifier 

Print  the  fully  qualified  form  of  all  the  symbols  whose  names  match  the  given  identifier. 
The  order  in  which  the  symbols  are  displayed  is  not  meaningful. 

assign  variable  =  expression 
set  variable  =  expression 

Assign  the  value  of  the  expression  to  the  variable.  Currently  no  type  conversion  takes 
place  if  operands  are  of  different  types, 

call  procedurefparameters) 

Execute  the  object  code  associated  with  the  named  procedure  or  function.  If  execution 
encounters  any  breakpoints,  execution  halts  and  the  dbx  command  level  is  re-entered.  A 
stack  trace  with  the  where  command  shows  that  the  call  originated  from  the  dbx  com¬ 
mand  level. 

If  the  source  file  that  the  routine  is  defined  in  was  compiled  with  the  -g  flag,  the  number 
and  types  of  parameters  must  match.  However,  if  C  routines  are  called  which  are  not 
compiled  with  the  -g  flag,  dbx  will  not  do  parameter  checking;  the  parameters  are  simply 
pushed  onto  the  stack  as  given  in  the  parameter  list.  Currently,  string  and  structure 
parameters  are  not  passed  properly  for  C  and  parameters  greater  than  four  bytes  in 
length  (for  example,  complex  and  double  precision  variables)  and  alternate  return  points 
are  not  passed  properly  for  FORTRAN. 

where  \n] 

Display  a  list  of  the  top  n  active  procedures  and  functions  on  the  stack.  If  n  is  not 
specified,  it  displays  all  active  procedures  and  functions. 

dump  \func\ 

Display  the  names  and  values  of  all  the  local  variables  and  parameters  in  /unc.  If  func  is 
not  specified  the  current  function  is  used. 

up  \  n\  Move  up  (towards  ”main**)  the  call  stack  n  levels.  If  n  is  not  specified,  the  default  is  one. 
This  command  allows  you  to  examine  the  local  variables  in  functions  other  than  the 
current  one.  In  dbxtool,  the  line  containing  the  call  is  hilighted  for  one  second. 

down  I  n  ] 

Move  down  (towards  the  current  stopping  point)  the  call  stack  n  levels.  If  n  is  not 
specified,  the  default  is  one.  In  dbxtool,  the  line  containing  the  call  is  hilighted  for  one 
second. 

3.  Accessing  Source  Files  &  Directories 

edit  [filename] 

edit  procedure/function’name 

Invoke  an  editor  on  filename  or  the  current  source  file  if  none  is  specified.  If  a  procedure 
or  function  name  is  specified,  the  editor  is  invoked  on  the  file  that  contains  it.  Which 
editor  is  invoked  by  default  depends  on  the  installation.  The  default  can  be  overridden 
by  setting  the  environment  variable  EDITOR  to  the  name  of  the  desired  editor. 

flic  [filename] 

Change  the  current  source  file  to  filename.  Print  the  name  of  the  current  source  file  if 
no  filename  is  specified. 

func  [procedure/ function/ program  name] 

Change  the  current  function.  Print  the  current  function  if  none  is  specified.  Changing 
the  current  function  implicitly  changes  the  current  source  file  variable  flie  to  the  one 
that  contains  the  function;  it  also  changes  the  current  scope  used  for  name  resolution.  If 
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the  entire  scope  of  the  program  is  desired,  the  argument  should  be  the  object  file  name. 

list  \$ource’lin€‘number  source~line‘number]\ 
list  procedure! function 

List  the  lines  in  the  current  source  file  from  the  first  line  number  through  the  second.  If 
no  lines  are  specified,  the  next  10  lines  are  listed.  If  the  name  of  a  procedure  or  function 
is  given  lines  n— 5  to  n+S  are  listed  where  n  is  the  first  statement  in  the  procedure  or 
function.  If  the  list  command’s  argument  is  a  procedure  or  function,  the  scope  for 
further  listing  is  changed  to  that  routine  —  use  the  file  command  to  change  it  back. 

use  \direciory‘li$t\ 

Set  the  list  of  directories  to  be  searched  when  looking  for  source  files.  Print  the  current 
list  of  directories  if  no  directory-lisi  is  given. 

cd  [ dirname] 

Change  dbx's  notion  of  the  current  directory  to  dirname.  With  no  argument,  use  the 
value  of  the  HOME  environment  variable. 

pwd  Print  dbx's  notion  of  the  current  directory. 

f$tring\/\ 

Search  down  the  current  file  for  the  regular  expression  siring.  The  search  begins  with 
the  line  immediately  after  the  current  line  and,  if  necessary,  continues  until  the  end  of 
the  file.  The  matching  line  becomes  the  current  line.  In  dbxtool,  the  matching  line  is 
hilighted  for  one  second. 

Search  up  the  current  file  for  the  regular  expression  string.  The  search  begins  with  the 
line  immediately  before  the  current  line  and,  if  necessary,  continues  until  the  top  of  the 
file.  The  matching  line  becomes  the  current  line.  In  dbxtool,  the  matching  line  is 
hilighted  for  one  second. 

When  dbx  is  searching  for  a  source  file,  the  value  of  'file’  and  the  ‘use’  directory  search  path  is 
used.  The  value  of  'file’  is  appended  to  each  directory  in  the  ‘use’  search  path  until  a  file  is 
found.  This  file  becomes  the  current  file. 

Dbx  knows  the  same  file  names  that  are  given  to  the  compilers.  For  instance,  if  a  file  is  compiled 
with  the  command  %  cc  -c  -g  ../mip/scan.c  then  dbz  knows  of  the  file  ••/mip/scan^c,  but  it 
does  not  know  of  the  file  Bcan«e. 

4,  Machine-Level  Commands 

trace!  [address]  [If  cond| 
trace!  [variable]  |at  (If  cond| 

stop!  [variable]  [it  cond] 
stop!  [at]  (addre^^j  (if  cond] 

Turn  on  tracing  or  set  a  breakpoint  at  a  machine  instruction  address. 

step! 

next! 

Single  step  as  in  step  or  next,  but  do  a  single  machine  instruction  rather  than  a  source 
line. 

address  ^address/  [  mode  | 

[address]  !  [count]  (mode] 

Display  the  contents  of  memory  starting  at  the  first  address  and  continuing  up  to  the 
second  address  or  until  count  items  have  been  displayed.  If  no  address  is  specified,  the 
address  following  the  one  displayed  most  recently  is  used.  The  mode  specifies  how  memory 
is  to  be  displayed;  if  it  is  omitted  the  last  previously  specified  mode  is  used.  The  initial 
mode  is  ‘X’.  The  following  modes  are  supported: 
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1 

display 

d 

display 

D 

display 

o 

display 

O 

display 

X 

display 

X 

display 

b 

display 

e 

display 

s 

display 

f 

display 

S 

display 

the  machine  instruction 
a  word  in  decimal 
a  longword  in  decimal 
a  word  in  octal 
a  longword  in  octal 
a  word  in  hexadecimal 
a  longword  in  hexadecimal 
a  byte  in  octal 
a  byte  as  a  character 

a  string  of  characters  terminated  by  a  null  byte 
a  single  precision  real  number 
a  double  precision  real  number 


Symbolic  addresses  used  in  this  context  are  specified  by  preceding  a  name  with  an  Registers 
are  denoted  by  '$d0-$d7’  (data  registers),  ‘$a0“$a7’  (address  registers),  *$fp’  (frame  pointer),  ‘$sp* 
(stack  pointer),  and  ‘$pc’  (program  counter).  Note  that  $fp  is  equivalent  to  register  a6  and  $sp  is 
equivalent  to  register  a7.  For  example,  to  print  the  contents  of  all  registers  in  hex,  one  would 
type  “&$d0/20X”  or  ‘*&$dO,&$a7/X’\  To  print  the  contents  of  register  dO,  one  could  also  type 
“print  $d0”  (one  cannot  currently  specify  a  range  with  print).  Addresses  may  be  expressions 
made  up  of  other  addresses  and  the  operators  and  indirection  (unary  ‘*’). 


5.  Miscellaneous  Commands 

sh  command- line 

Pass  the  command  line  to  the  shell  for  execution.  The  SHELL  environment  variable 
determines  which  shell  is  used. 

alias  new- command-name  character-sequence 

Respond  to  new-command-name  as  though  it  were  character-sequence.  Special  charac¬ 
ters  occurring  in  character-sequence  must  be  enclosed  in  quotation  marks.  Alias  substi¬ 
tution  ala  the  C  shell  (c^A(l))  also  occurs. 

help  [command] 

help  Print  a  short  message  explaining  command.  If  no  argument  is  given,  display  a  synopsis  of 
dbx  commands. 

source  Read  dbx  commands  from  the  given  filename.  This  is  especially  useful  when  the  filename 
has  been  created  by  redirecting  a  status  command  from  an  earlier  debugging  session. 

quit  Exit  dbx. 

dbxenv  strtnglen  num 
dbxenv 

Set  dbx  attributes.  The  only  one  currently  supported  is  strlnglen  which  controls  the 
maximum  number  of  characters  printed  for  a  “char  ♦”  variable  in  a  C  program.  The 
dbxenv  command  with  no  argument  prints  the  attributes  and  their  current  values. 

debug  [  objfile  [corefiie]] 

Terminate  debugging  of  the  current  program  (if  any)  and  begin  debugging  the  one  found 
in  objfiUf  without  incurring  the  overhead  of  reinitializing  dbx.  If  no  arguments  are 
specified,  the  name  of  the  program  currently  being  debugged  and  its  arguments  is 
printed. 

kill  Terminate  debugging  of  the  current  program,  but  leave  dbx  ready  to  debug  another. 
This  is  particularly  useful  to  eliminate  remains  of  a  window  program  one  was  debugging 
without  exiting  the  debugger  or  to  allow  the  object  file  to  be  removed  and  remade 
without  incurring  a  **text  file  busy"  error  message. 
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Debugging  Procesaes  that  Fork 

Debugging  a  process  that  /ark(2)s  introduces  unique  problems.  Dbz  uses  the  plraee(2)  interface 
to  fetch  from  and  store  into  the  debuggee.  This  interface  requires  that  the  debugger  be  the 
parent  process  of  the  debuggee.  If  the  debuggee  forks,  the  child  of  the  fork  is  the  grandchild  of 
dbx  and  it  cannot  be  debugged.  No  breakpoints  should  be  set  in  the  code  that  is  executed  by  the 
child  of  the  fork.  If  the  child  of  the  fork  trips  over  a  breakpoint,  it  will  die. 

When  the  debuggee  forks,  it  can  still  be  debugged  with  a  few  caveats.  After  the  fork,  there  are 
two  processes  that  are  sharing  the  same  text  (code)  space.  The  kernel  does  not  allow  ptfttce  to 
write  into  a  text  space  that  is  being  used  by  more  than  one  process.  This  means  the  debuggee 
should  not  trip  over  any  breakpoints  while  the  child  of  the  fork  is  still  sharing  its  text  space.  In 
most  cases,  the  child  of  the  fork  will  exec{2)  a  new  program  almost  immediately.  After  the  exec, 
it  is  safe  for  the  debuggee  to  trip  over  breakpoints.  Therefore,  it  is  recommended  that  a  sleep(2) 
of  two  or  three  seconds  be  placed  in  the  debuggee  immediately  after  the  fork.  This  gives  the 
child  of  the  fork  some  time  to  exec  a  new  program  and  get  out  of  the  way. 

FILES 

a.out 
core 

■/.dbxlnit 

SEE  ALSO 

cc(l)  C  compiler 
r77(l)  FORTRAN  compiler 
pc(l)  Pascal  compiler 

COMMENTS 

Dbx  suffers  from  a  ‘multiple  include’  malady.  If  a  program  consists  of  a  number  of  object  files 
and  each  is  built  from  source  files  that  include  header  files,  the  symbolic  information  for  the 
header  files  is  replicated  in  each  object  file.  Since  roughly  debugger  start-up  is  done  for  each 
link,  having  the  linker  (Id)  reorganize  the  symbol  information  won’t  save  much  time,  though  it 
does  reduce  the  disk  space  used.  The  problem  is  an  artifact  of  the  unrestricted  semantics  of 
#include’s  in  C;  for  example  an  include  file  can  contain  static  declarations  that  are  separate  enti¬ 
ties  for  each  file  in  which  they  are  included. 

BUGS 

Dbx  does  not  correctly  handle  C  variables  that  are  local  to  compound  statements.  When  printing 
these  variables  it  often  gives  incorrect  results. 

Dbx  does  not  handle  FORTRAN  entry  points  well  —  it  treats  them  as  if  they  were  independent 
routines. 

Dbx  does  not  handle  assigning  to  FORTRAN  complex  types  correctly  (see  the  assignfset  com¬ 
mand). 

The  use  command  and  -I  option  do  not  override  the  current  directory  if  there  is  source  by  the 
same  name  in  the  current  directory. 

Some  operations  behave  differently  in  dbx  than  in  C. 

•  Dbx  has  two  division  operators  —  /  always  yields  a  floating  point  result  and  dlv  always 
yields  an  integral  result. 

•  An  array  or  function  name  does  not  imply  the  address  of  the  array  or  function  in  dbx. 
An  array  name  implies  the  entire  array,  and  a  function  name  implies  a  call  to  the  func¬ 
tion  with  no  arguments.  The  address  of  an  array  can  be  obtained  by  taking  the  address 
of  the  array’s  first  element,  and  the  address  of  function  can  be  obtained  by  taking  the 
address  of  the  function’s  name. 


default  object  file 
default  core  file 
initial  commands 
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Casts  do  not  work  with  FORTRAN  or  Pascal. 

String  and  structure  parameters  are  not  passed  properly  for  C  and  parameters  greater  than  four 
bytes  in  length  (for  example,  complex  and  double  precision  variables)  and  alternate  return  points 
are  not  passed  properly  for  FORTRAN. 


Q 


Sun  Release  2.0 


Last  change:  1  February  1985 


89 


DBXTOOL(l) 


USER  COMMANDS 


DBXTOOL(l) 


NAME 

dbxtool  —  window-  and  mouse-based  debugging  tool 


SYNOPSIS 

dbxtool  I  —I  I  I  —1  dir  ]  \  objfile  [  corefile  ]  | 

DESCRIPTION 

Dbxtool  is  a  source-level  debugger  with  a  window  and  mouse-based  user  interface.  It  accepts  the 
same  commands  as  dbx  (1),  but  provides  a  more  convenient  user  interface.  Using  the  mouse,  one 
can  set  breakpoints,  examine  the  values  of  variables,  control  execution,  peruse  source  files  and  so 
on.  Dbxtool  has  separate  subwindows  for  viewing  source  code,  entering  commands  and  several 
other  uses.  It  functions  in  the  suntool8{l)  environment,  so  that  the  standard  tool  manager 
actions,  such  as  moving,  stretching,  exposing  etc.  can  be  applied  to  it. 

Objfile  is  an  object  file  produced  by  cc  (1),  f77  (l)  or  pc  (1)  (or  a  combination  of  them)  with  the 
appropriate  flag  (— g)  specified  to  produce  symbol  information  in  the  object  file.  IMPORTANT: 
every  stage  of  the  compilation  process,  including  the  loading  phase,  must  include  the  — g  option. 
If  no  objfile  is  specified,  one  uses  the  debug  command  to  specify  the  program  to  be  debugged. 
The  object  file  contains  a  symbol  table  which  includes  the  names  of  all  the  source  files  translated 
by  the  compiler  to  create  it.  These  files  are  available  for  perusal  while  using  the  debugger. 

If  a  file  named  core  exists  in  the  current  directory  or  a  corefile  is  specified,  dbxtool  can  be  used  to 
examine  the  state  of  the  program  when  it  faulted. 

Debugger  commands  in  the  file  .dbxinit  are  executed  immediately  after  the  symbolic  information 
is  read,  if  that  file  exists  in  the  current  directory,  or  in  the  user’s  home  directory  if  Mxinit 
doesn’t  exist  in  the  current  directory. 


OPTIONS 

—I  Force  dbxtool  to  act  as  though  standard  input  were  a  terminal. 

—I  dir  Add  dir  to  the  list  of  directories  that  are  searched  when  looking  for  a  source  file.  Nor¬ 
mally  dbxtool  looks  for  source  files  in  the  current  directory  and  then  in  the  directory 
where  objfile  is  located.  The  directory  search  path  can  also  be  set  with  the  use  com¬ 
mand,  Multiple  —I  options  may  be  given. 


SUBWINDOWS 

Dbxtool  consists  of  five  sub  windows.  From  top  to  bottom  they  are: 

status  the  location  of  the  point  at  which  execution  is  currently  stopped  and  a  description 

of  the  lines  displayed  in  the  source  subwindow  are  displayed  in  the  status  subwin¬ 
dow. 


source 

buttons 


command 


display 


displays  source  text  of  the  program  being  debugged. 

software  buttons  corresponding  to  the  most  frequently  used  commands  are  provided 
in  the  buttons  subwindow.  Picking  a  button  with  the  mouse  invokes  the  command 
associated  with  that  button. 

provides  a  typing  interface  to  dbxtool  to  supplement  the  buttons  subwindow  and 
mouse.  Also,  most  of  the  output  generated  by  commands  appears  in  this  subwin¬ 
dow. 

provides  a  way  of  tracking  the  values  of  selected  variables  by  updating  a  display  of 
their  values  each  time  execution  stops. 


SCROLLING 

The  source  f  command,  and  display  windows  have  scroll  bars  to  facilitate  browsing  their  con¬ 
tents.  The  scroll  bar  is  at  the  left  edge  of  each  window.  The  bar  is  a  medium  gray  background 
with  a  darker  gray  area  superimposed  over  it  indicating  the  portion  of  the  source  file,  command 
transcript  or  display  currently  visible  in  the  window.  Note  that  the  size  of  the  darker  gray  area 
corresponds  to  the  number  of  characters  visible  in  the  source  window,  not  the  number  of  lines. 
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Within  the  scroll  bar,  the  mouse  buttons  have  the  following  functions; 

left  scroll  forward,  move  towards  the  end  of  the  file 

middle  scroll  to  absolute  position  in  the  text 

right  scroll  backwards,  move  towards  the  beginning  of  the  file 

Positioning  the  cursor  within  the  scroll  bar  next  to  a  given  line  and  clicking  the  left  button  causes 
the  line  to  move  to  the  top  of  the  window.  Clicking  the  right  button  causes  the  top  line  in  the 
window  to  move  to  the  position  of  the  cursor. 

The  middle  button  treats  the  scroll  bar  as  a  thumb  bar.  The  top  of  the  thumb  bar  represents 
the  beginning  of  the  text  and  the  bottom  represents  the  end  of  the  text.  Clicking  the  middle  but¬ 
ton  in  the  scroll  bar  picks  a  point  within  the  text  relative  to  its  entire  size.  This  point  is 
displayed  at  the  top  of  the  window. 

THE  SOURCE  WINDOW 

The  source  window  displays  the  text  of  the  program  being  debugged.  Initially,  it  displays  text 
from  either  the  main  routine,  if  there  is  no  core  file,  or  the  point  at  which  execution  stopped,  if 
there  is  a  core  file.  Whenever  execution  stops  during  a  debugging  session,  it  displays  the  point  at 
which  it  stopped.  The  file  command  can  be  used  to  switch  the  source  window  to  another  file; 
the  focus  of  attention  moves  to  the  beginning  of  the  new  file.  Similarly,  the  func  command  can 
be  used  to  switch  the  source  window  to  another  function;  the  new  focus  of  attention  is  the  first 
executable  line  in  the  function. 

Breakpoints  are  indicated  in  the  source  window  by  a  solid  stop  sign  at  the  beginning  of  the  line. 
The  point  at  which  execution  is  currently  stopped  is  marked  by  a  rightward  pointing  outlined 
arrow. 


COMMAND  CONSTRUCTION 

One  can  either  type  commands  to  dbxtool  or  construct  them  with  the  selection  and  button 
mechanism  (if  a  button  is  provided  for  the  command),  but  typing  and  buttons  cannot  be  com¬ 
bined. 


A  selection  is  made  by  pointing  the  mouse  at  one  end  of  the  desired  text  and  clicking  the  left  but¬ 
ton  and  then  pointing  the  mouse  at  the  other  end  of  the  text  and  clicking  the  middle  button. 
The  selected  text  is  hillghted  in  reverse-video.  In  the  command  window,  pressing  the  right  but¬ 
ton  brings  up  a  “stuff”  menu,  which,  when  chosen,  causes  the  selected  text  to  be  stuffed  into  the 
command  window’s  input  stream  as  if  it  had  been  typed  from  the  keyboard.  Holding  down  the 
SHIFT  key  and  clicking  the  right  button  is  an  accelerator  that  automatically  stuffs  the  selection 
without  bringing  up  a  menu. 

The  software  buttons  operate  in  a  postfix  manner.  That  is,  one  first  selects  the  arguments  and 
then  clicks  the  software  button  with  the  left  mouse  button.  Each  command  interprets  the  selec¬ 
tion  as  appropriate  for  that  command. 


There  arc  five  ways  in  which  dbxtool  may  interpret  a  selection: 


literal 

expand 


lineno 

command 


A  selection  may  be  interpreted  as  representing  exactly  the  selected  material. 

A  selection  may  be  interpreted  as  representing  exactly  the  selected  material, 
with  the  exception  that  it  will  be  expanded  if  either  the  first  or  last  charac¬ 
ter  of  the  selection  is  an  alphanumeric  character  or  underscore.  It  will  be 
expanded  to  the  longest  enclosing  sequence  of  alphanumeric  characters  or 
underscores.  Selections  made  outside  of  dbxtool  cannot  be  expanded  and 
are  interpreted  as  exactly  the  selected  text. 

A  selection  in  the  source  window  may  be  interpreted  as  representing  the 
(line  number  of  the)  first  source  line  containing  all  or  some  of  the  selection. 

A  selection  in  the  command  window  may  be  interpreted  as  representing  the 
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command  containing  the  selection. 


ignore  Buttons  may  ignore  a  selection. 

COMMAND  BUTTONS 

The  standard  set  of  command  buttons  in  the  buttons  window  is  as  follows, 

print  Prints  the  value  of  a  variable  or  expression.  It  uses  the  whole  selection,  except  that  if 
the  selection  string  begins  or  ends  with  an  alphanumeric  character  or  underscore,  the 
string  is  first  expanded  from  both  ends  to  the  longest  enclosing  string  containing  only 
alphanumerics  and  underscores.  Thus,  an  identifier  can  be  printed  by  selecting  as  little 
as  one  character  within  it. 

next  Executes  one  source  line  and  then  stops  execution,  except  that  if  the  current  source  line 
is  a  procedure  or  function  call  it  executes  through  the  called  routine  before  stopping. 
The  next  button  ignores  the  selection. 

step  Executes  one  source  line  and  then  stops  execution  again.  If  the  current  source  line  is  a 
procedure  or  function  call  it  stops  at  the  first  executable  line  within  the  procedure  or 
function.  The  step  button  ignores  the  selection. 

Sets  a  breakpoint  at  a  given  source  line.  It  interprets  a  selection  in  the  source  window 
as  representing  the  line  number  associated  with  the  first  line  of  the  selection. 

Resumes  execution  from  the  point  at  which  it  is  currently  stopped.  The  coni  button 
ignores  the  selection. 

Sets  a  breakpoint  at  the  first  line  of  a  given  function  or  procedure.  It  interprets  the 
selection  in  the  same  manner  as  the  print  button,  i.e,  selecting  an  occurrence  of  a  pro¬ 
cedure  or  function  name  causes  a  breakpoint  to  be  set  in  the  corresponding  routine. 

Causes  a  selected  command  to  be  repeated.  It  interprets  a  selection  in  the  command 
window  as  representing  the  command  containing  the  selection. 

CHOOSING  YOUR  OWN  BUTTONS 

The  button  command  may  be  used  to  define  command  buttons  in  the  buttons  window.  It  may 
be  used  in  ,dbxinit  to  define  buttons  in  addition  to  the  default  set  of  buttons,  or  during  a  debug¬ 
ging  session  to  add  new  buttons.  The  first  argument  to  button  is  the  selection  interpretation  to 
be  used  for  the  button  and  the  remainder  is  the  command  to  be  associated  with  it.  The  default 
set  of  buttons  can  be  replicated  by  the  sequence 

button  expand  print 
button  ignore  next 
button  ignore  step 
button  lineno  stop  at 
button  ignore  cont 
button  expand  stop  in 
button  command  redo 

The  unbutton  command  my  be  used  in  .dbxinit  to  remove  a  default  button  from  the  buttons 
window,  or  during  a  debugging  session  to  remove  any  existing  buttons.  The  arguments  to  the 
unbutton  command  are  the  same  as  for  the  button  command  —  a  selection  interpretation  fol¬ 
lowed  by  a  command. 

THE  DISPLAY  WINDOW 

The  display  window  is  used  to  provide  continual  feedback  of  the  values  of  a  selected  set  of  vari¬ 
ables.  The  display  command  specifies  variables  to  appear  in  the  display  window  and  undlsplay 
removes  them.  Each  time  execution  of  the  program  being  debugged  stops,  the  values  of  the 


stop  at 
cont 
stop  in 

redo 
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displayed  variables  are  updated. 

CONTROLLING  THE  DBXTOOL  ENVIRONMENT 

The  toolenv  command  provides  control  over  several  facets  of  the  dhxiool  window  environment, 
including  the  font,  the  vertical  size  of  the  acurcty  command  and  display  windows,  the  horizontal 
size  of  the  tool,  and  the  minimum  number  of  lines  between  the  top  or  bottom  of  the  source  win¬ 
dow  and  the  arrow.  These  are  chiefly  useful  in  the  ,dhxinit  file  to  control  initialization  of  the 
tool,  but  may  be  issued  at  any  time. 

OTHER  ASPECTS  OF  DBXTOOL 

The  commands,  expression  syntax,  scope  rules,  etc.  of  dhxiool  are  identical  to  those  for  dhx  (1). 
Three  of  the  commands,  toolenv,  button,  and  unbutton  affect  only  dhxiool,  and  so  they  are 
described  below.  See  the  dhx  (1)  manual  entry  for  a  description  of  the  others. 

toolenv  aitrihuie  value 

Set  attributes  of  the  dhxiool  window.  This  command  has  no  effect  in  dhx.  The  toolenv 
command  with  no  arguments  prints  the  current  values  of  the  attributes.  The  possible 
aiirihute- value  pairs  and  their  interpretations  are  as  follows: 

font  font  file 

change  the  font  to  that  found  in  fonijile\  default  is  taken  from  the 
DEFAULT J'ONT  shell  variable 

width  n chars 

change  the  width  of  the  tool  window  to  nchars  characters;  default  is  80  charac¬ 
ters 

sr dines  nlines 

make  the  source  subwindow  nlines  high;  default  is  20  lines 
cmdlines  nlines 

make  the  command  subwindow  nlines  high;  default  is  12  lines 
dlsplinea  nlines 

make  the  display  subwindow  nlines  high;  default  is  3  lines 

top  margin  nlines 

keep  the  line  with  the  arrow  at  least  nlines  from  the  top  of  the  source  subwin¬ 
dow;  default  is  3  lines 

botmargin  nlines 

keep  the  line  with  the  arrow  on  it  at  least  nlines  from  the  bottom  of  the  source 
subwindow;  default  is  3  lines 

button  seleciion  command^name 

Associate  a  button  with  a  command  in  dhxtooL  This  command  has  no  effect  on 
dhx.  Selection  is  described  in  the  Command  Consiruction  section  above. 

unbutton  selection  command-name 

Remove  a  button  from  the  huiions  window.  The  button  with  a  matching  selec¬ 
tion  and  command-name  is  removed. 

FILES 

a.out  default  object  file 

core  default  core  file 

"'/.dbxinit  initial  commands 

SEE  ALSO 

cc(l)  C  compiler 
f77(l)  FORTRAN  compiler 


Sun  Release  2.0 


Last  change:  26  March  1985 


93 


DBXTOOL(l) 


USER  COMMANDS 


DBXTOOL(]l) 


pc(l)  Pascal  compiler 
COMMENTS 

The  comments  listed  for  dbx  (1)  apply  to  dbxtool  as  well 

BUGS 

The  bugs  listed  for  dbx  (1)  apply  to  dbxtool  as  well 

The  selection  mechanism  of  ttytool  and  dbxtool  should  be  the  same,  Dbxtool  does  not  have 
multi-clicking  selections. 

The  interaction  between  scrolling  in  the  source  subwindow  and  dbx^s  regular  expression  search 
commands  is  wrong.  Scrolling  should  affect  where  the  next  search  begins,  but  it  does  not. 
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NAME 

dc  —  desk  calculator 

SYNOPSIS 

dc  [  file  I 

DESCRIPTION 

Dc  is  an  arbitrary  precision  arithmetic  package.  Ordinarily  it  operates  on  decimal  integers,  but 
one  may  specify  an  Input  base,  output  base,  and  a  number  of  fractional  digits  to  be  maintained. 
The  overall  structure  of  dc  is  a  stacking  (reverse  Polish)  calculator.  If  an  argument  is  given, 
input  is  taken  from  that  file  until  its  end,  then  from  the  standard  input.  The  following  construc¬ 
tions  are  recognized: 

number 

The  value  of  the  number  is  pushed  on  the  stack.  A  number  is  an  unbroken  string  of  the 
digits  0-9,  It  may  be  preceded  by  an  underscore  _  to  input  a  negative  number.  Numbers 
may  contain  decimal  points. 

+  -/  *  %  ^ 

The  top  two  values  on  the  stack  are  added  (+),  subtracted  (-),  multiplied  (♦),  divided  (/), 
remaindered  (%),  or  exponentiated  (").  The  two  entries  are  popped  off  the  stack;  the 
result  is  pushed  on  the  stack  in  their  place.  Any  fractional  part  of  an  exponent  is  ignored. 

sx  The  top  of  the  stack  is  popped  and  stored  into  a  register  named  z,  where  x  may  be  any 
character.  If  the  a  is  capitalized,  x  is  treated  as  a  stack  and  the  value  is  pushed  on  it. 

lx  The  value  in  register  x  is  pushed  on  the  stack.  The  register  x  is  not  altered.  All  registers 
start  with  zero  value.  If  the  1  is  capitalized,  register  x  is  treated  as  a  stack  and  its  top 
value  is  popped  onto  the  main  stack. 

d  The  top  value  on  the  stack  is  duplicated. 

p  The  top  value  on  the  stack  is  printed.  The  top  value  remains  unchanged.  P  interprets 
the  top  of  the  stack  as  an  ascii  string,  removes  it,  and  prints  it. 

f  All  values  on  the  stack  and  in  registers  are  printed. 

q  exits  the  program.  If  executing  a  string,  the  recursion  level  is  popped  by  two.  If  q  is  capi¬ 
talized,  the  top  value  on  the  stack  is  popped  and  the  string  execution  level  is  popped  by 
that  value, 

X  treats  the  top  element  of  the  stack  as  a  character  string  and  executes  it  as  a  string  of  dc 
commands. 

X  replaces  the  number  on  the  top  of  the  stack  with  its  scale  factor. 

[  ]  puts  the  bracketed  ascii  string  onto  the  top  of  the  stack. 

<2:  >x  =^x 

The  top  two  elements  of  the  stack  are  popped  and  compared.  Register  x  is  executed  if 
they  obey  the  stated  relation. 

V  replaces  the  top  element  on  the  stack  by  its  square  root.  Any  existing  fractional  part  of 
the  argument  is  taken  into  account,  but  otherwise  the  scale  factor  is  ignored. 

f  interprets  the  rest  of  the  line  as  a  UNIX  command. 

c  All  values  on  the  stack  are  popped. 

I  The  top  value  on  the  stack  is  popped  and  used  as  the  number  radix  for  further  input.  I 
pushes  the  input  base  on  the  top  of  the  stack. 

o  The  top  value  on  the  stack  is  popped  and  used  as  the  number  radix  for  further  output. 

O  pushes  the  output  base  on  the  top  of  the  stack. 
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k  the  top  of  the  stack  is  popped,  and  that  value  is  used  as  a  non-negative  scale  factor:  the 
appropriate  number  of  places  are  printed  on  output,  and  maintained  during  multiplication, 
division,  and  exponentiation.  The  interaction  of  scale  factor,  input  base,  and  output  base 
will  be  reasonable  if  all  are  changed  together. 

E  The  stack  level  is  pushed  onto  the  stack. 

Z  replaces  the  number  on  the  top  of  the  stack  with  its  length. 

?  A  line  of  input  is  taken  from  the  input  source  (usually  the  terminal)  and  executed. 

5  :  are  used  by  4c  for  array  operations. 

EXAMPLE 

Print  the  first  ten  values  of  n! 

[lal+dsa*plal0>y|sy 

Osal 

lyx 

SEE  ALSO 

bc(l),  which  is  a  preprocessor  for  dc  providing  infix  notation  and  a  C-like  syntax  which  imple¬ 
ments  functions  and  reasonable  control  structures  for  programs. 

DIAGNOSTICS 

'x  is  unimplemented’  where  x  is  an  octal  number. 

‘stack  empty’  for  not  enough  elements  on  the  stack  to  do  what  was  asked. 

‘Out  of  space’  when  the  free  list  is  exhausted  (too  many  digits). 

‘Out  of  headers’  for  too  many  numbers  being  kept  around. 

‘Out  of  pushdown’  for  too  many  items  on  the  stack. 

‘Nesting  Depth’  for  too  many  levels  of  nested  execution. 
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NAME 

dd  -  convert  and  copy  a  file 

SYNOPSIS 

dd  [op tion= value]  ... 

DESCRIPTION 

Dd  copies  a  specified  input  file  to  a  specified  output  with  possible  conversions.  The  standard 
input  and  output  are  used  by  default.  The  input  and  output  block  size  may  be  specified  to  take 
advantage  of  raw  physical  I/O. 

OPTION  VALUES 

If— nome  input  file  is  taken  from  namt;  standard  input  is  default. 

of=name  output  file  is  taken  from  nome;  standard  output  is  default.  Note  that  dd  creates 

and  explicit  output  file;  therefore  the  seek  option  is  usually  useless  with  explicit 
output  except  in  special  cases  such  as  using  magnetic  tape  or  raw  disk  files. 

Ibs^n  input  block  size  n  bytes  (default  512). 

obB=n  output  block  size  n  bytes  (default  512). 

hs=n  set  both  input  and  output  block  size,  superseding  lbs  and  ob»;  also,  if  no  conver¬ 

sion  is  specified,  it  is  particularly  efficient  since  no  copy  need  be  done 

cb8=n  conversion  buffer  size 

skip— n  skip  n  input  records  before  starting  copy 

flleB=n  copy  n  input  files  before  terminating  (makes  sense  only  when  input  is  a  magtape 

or  similar  device). 

seek^n  seek  n  records  from  beginning  of  output  file  before  copying.  This  option  gen¬ 

erally  only  works  with  magnetic  tapes  and  raw  disk  files  and  is  otherwise  usually 
useless  if  the  explicit  output  file  was  named  with  the  of  option. 

count=n  copy  only  n  input  records 

conv=ascii  convert  EBCDIC  to  ASCII 

ebcdic  convert  ASCII  to  EBCDIC 

ibm  slightly  different  map  of  ASCII  to  EBCDIC 
block  convert  variable  length  records  to  fixed  length 
unblock  convert  fixed  length  records  to  variable  length 
lease  map  alphabetics  to  lower  case 

ucase  map  alphabetics  to  upper  case 

swab  swap  every  pair  of  bytes 

noerror  do  not  stop  processing  on  an  error 

sync  pad  every  input  record  to  ib8 

...  ,  ...  several  comma-separated  conversions 

Where  sizes  are  specified,  a  number  of  bytes  is  expected.  A  number  may  end  with  k  (kilobytes) 
to  specify  multiplication  by  1024,  b  (blocks  of  512  bytes)  to  specify  multiplication  by  612,  or  w 
(words)  to  specify  multiplication  by  4;  a  pair  of  numbers  may  be  separated  by  x  to  indicate  a  pro¬ 
duct. 

CbB  is  used  only  if  ascU,  unblock,  ebcdic,  Ibm,  or  block  conversion  is  specified.  In  the  first 
two  cases,  cbB  characters  are  placed  into  the  conversion  buffer,  any  specified  character  mapping 
is  done,  trailing  blanks  trimmed  and  new-line  added  before  sending  the  line  to  the  output.  In  the 
latter  three  cases,  characters  are  read  into  the  conversion  buffer,  and  blanks  added  to  make  up 
an  output  record  of  size  cbB. 
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After  completion,  dd  reports  the  number  of  whole  and  partial  input  and  output  blocks. 
EXAMPLE 

To  read  an  EBCDIC  tape  blocked  ten  80-byte  EBCDIC  card  images  per  record  into  the  ASCII  file 
z: 

tutoriaI%  dd  lf=/dev/rmtO  of=x  Iba=800  eb8=80  conv=a8ciI, lease 

Note  the  use  of  raw  magtape:  dd  is  especially  suited  to  I/O  on  the  raw  physical  devices  because  it 
allows  reading  and  writing  in  arbitrary  record  sizes. 

SEE  ALSO 

cp(l),  tr(l) 

DIAGNOSTICS 

f+p  records  in(out):  numbers  of  full  and  partial  records  read(written) 

BUGS 

The  ASCn/EBCDIC  conversion  tables  are  taken  from  the  255  character  standard  in  the  CACM 
Nov,  1968.  The  Ibm  conversion,  while  less  blessed  as  a  standard,  corresponds  better  to  certain 
IBM  print  train  conventions.  There  is  no  universal  solution. 

The  block  and  unblock  options  cannot  be  combined  with  the  ascii,  ebcdie  or  Ibm.  Inalld  cobi¬ 
nations  silently  ignore  all  but  the  last  mutually-exclusive  keyword. 
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NAME 

delta  —  make  a  delta  (change)  to  an  SCCS  file 
SYNOPSIS 

/uar/sccs/delta  ]  -r  5/Z)  ]  [  -■  ]  [  -n  ]  [  |  (  -m|  mr/w<]  ]  [  -y[  comment]  |  (  -p  1  file 

•  •  • 

DESCRIPTION 

Delta  permanently  introduces  into  the  named  SCCS  file  changes  that  were  made  to  the  file 
retrieved  by  ^e^(l)  (called  the  g^file,  or  generated  file). 

Delta  makes  a  delta  to  each  named  SCCS  file.  If  a  directory  is  named,  delta  behaves  as  though 
each  file  in  the  directory  were  specified  as  a  named  file,  except  that  non-SCCS  files  (last  com¬ 
ponent  of  the  path  name  does  not  begin  with  and  unreadable  files  are  silently  ignored.  If  a 
name  of  —  is  given,  the  standard  input  is  read  (see  WARNINGS);  each  line  of  the  standard  input 
is  taken  to  be  the  name  of  an  SCCS  file  to  be  processed. 

Delta  may  issue  prompts  on  the  standard  output  depending  upon  certain  options  specified  and 
flags  (see  a</mm(l))  that  may  be  present  in  the  SCCS  file  (see  — m  and  — y  options  below). 

OPTIONS 

Options  apply  independently  to  each  named  file. 

— rS/D  Uniquely  identifies  which  delta  is  to  be  made  to  the  SCCS  file.  The  use  of  this  option  is 
necessary  only  if  two  or  more  outstanding  geVs  for  editing  (get  — e)  on  the  same  SCCS 
file  were  done  by  the  same  person  (login  name).  The  SID  value  specified  with  the 
option  can  be  either  the  SID  specified  on  the  get  command  line  or  the  SID  to  be  made  as 
reported  by  the  get  command  (see  ircf(l)).  A  diagnostic  results  if  the  specified  SID  is 
ambiguous,  or,  if  necessary  and  omitted  on  the  command  line. 

—8  Do  not  display  the  created  delta’s  SID,  number  of  lines  inserted,  deleted  and  unchanged 
in  the  SCCS  file. 

— n  Retain  the  edited  g-file  which  is  normally  removed  at  completion  of  delta  processing. 

— g/t>/  Specifies  a  list  of  deltas  to  be  ignored  when  the  file  is  accessed  at  the  change  level  (SID) 
created  by  this  delta.  See  ^e^(l)  for  the  definition  of  list 

— m  [  mrliBt] 

If  the  SCCS  file  has  the  v  flag  set  (see  udmzn(l)),  a  Modification  Request  (MR)  number 
must  be  supplied  as  the  reason  for  creating  the  new  delta. 

If  —m  is  not  used  and  the  standard  input  is  a  terminal,  the  prompt  MRsT  is  issued  on 
the  standard  output  before  the  standard  input  is  read;  if  the  standard  input  is  not  a  ter¬ 
minal,  no  prompt  is  issued.  The  MRs?  prompt  always  precedes  the  comments?  prompt 
(see  — y  option). 

MRs  in  a  list  are  separated  by  blanks  and/or  tab  characters.  An  unescaped  new-line 
character  terminates  the  MR  list. 

Note  that  if  the  v  flag  has  a  value  (see  urfmm(l)),  it  is  taken  to  be  the  name  of  a  pro¬ 
gram  (or  shell  procedure)  which  will  validate  the  correctness  of  the  MR  numbers.  If  a 
non-zero  exit  status  is  returned  from  MR  number  validation  program,  delta  terminates 
(it  is  assumed  that  the  MR  numbers  were  not  all  valid). 

—y  [comment] 

Arbitrary  text  to  describe  the  reason  for  making  the  delta.  A  null  string  is  considered  a 
valid  comment. 

If  — y  is  not  specified  and  the  standard  input  is  a  terminal,  the  prompt  commentsT  is 
issued  on  the  standard  output  before  the  standard  input  is  read;  if  the  standard  input  is 
not  a  terminal,  no  prompt  is  issued.  An  unescaped  new-line  character  terminates  the 
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comment  text. 

— p  Display  (on  the  standard  output)  the  SCCS  file  differences  before  and  after  the  delta  is 

applied  in  a  format. 

FILES 

All  files  of  the  form  ?-file  are  explained  in  the  Source  Code  Control  System  User *8  Guide.  The 
naming  convention  for  these  files  is  also  described  there. 

g-file  Existed  before  the  execution  of  delta]  removed  after  completion  of  delta. 

p-file  Existed  before  the  execution  of  delta]  may  exist  after  completion  of  delta. 

q-file  Created  during  the  execution  of  delta;  removed  after  completion  of  delta. 

x-file  Created  during  the  execution  of  delta;  renamed  to  SCCS  file  after  completion  of 

delta. 

Z'file  Created  during  the  execution  of  delta;  removed  during  the  execution  of  delta. 

d-file  Created  during  the  execution  of  delta;  removed  after  completion  of  delta. 

/bin/diff  Program  to  compute  differences  between  the  “gotten”  file  and  the  g-file. 

WARNINGS 

Lines  beginning  with  an  SOH  ASCII  character  (binary  001)  cannot  be  placed  in  the  SCCS  file 
unless  the  SOH  is  escaped.  This  character  has  special  meaning  to  SCCS  (see  8ccsfile{b))  and  will 
cause  an  error. 

A  get  of  many  SCCS  files,  followed  by  a  delta  of  those  files,  should  be  avoided  when  the  get  gen¬ 
erates  a  large  amount  of  data.  Instead,  multiple  get/ delta  sequences  should  be  used. 

If  the  standard  input  (— )  is  specified  on  the  delta  command  line,  the  — m  (if  necessary)  and  — y 
options  must  also  be  present.  Omission  of  these  options  is  an  error. 

SEE  ALSO 

sccs(l),  admin(l),  get(l),  he!p(l),  prs(l),  sccsfile(5). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 

DUGNOSTICS 

Use  kelp{l)  for  explanations. 
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NAME 

deroff  —  remove  nroff,  troff,  tbl  and  eqn  constructs 

SYNOPSIS 

deroff  [  — w  ]  file  ... 

DESCRIPTION 

Z>er()Jf  reads  each  file  in  sequence  and  removes  all  and  command  lines,  backslash  con¬ 
structions,  macro  definitions,  eqn  constructs  (between  ‘.EQ'  and  '.EN'  lines  or  between  delim¬ 
iters),  and  table  descriptions  and  writes  the  remainder  on  the  standard  output.  Deroff  follows 
chains  of  included  files  (‘.so’  and  *.nx*  commands);  if  a  file  has  already  been  included,  a  ‘.so’  is 
ignored  and  a  ‘.nx’  terminates  execution.  If  no  input  file  is  given,  deroff  reads  from  the  standard 
input  file. 

OPTIONS 

-^w  Generate  a  word  list,  one  word  per  line.  A  ‘word’  is  a  string  of  letters,  digits,  and  apos¬ 
trophes,  beginning  with  a  letter;  apostrophes  are  removed.  All  other  characters  are 
ignored. 

SEE  ALSO 

troff(l),  eqn(l),  tbl(l) 

BUGS 

Deroff  IS  not  a  complete  interpreter,  so  it  can  be  confused  by  subtle  constructs.  Most  errors 
result  in  too  much  rather  than  too  little  output. 

Deroff  does  not  work  well  with  files  that  use  .so  to  source  in  the  standard  macro  package  files. 
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NAME 

des  —  encrypt/decrypt  with  Data  Encryption  Standard 
SYNOPSIS 

des  -e  I  -d  [  -b  I  I  — f  ]  [  -k  )  [  -s  ]  [  infile  \  outfile  j  ] 

DESCRIPTION 

Des  encrypts  and  decrypts  data  using  the  NBS  Data  Encryption  Standard  algorithm.  One  of  -e 
(for  encrypt)  or  -d  (for  decrypt)  must  be  specified. 

The  des  command  is  provided  to  promote  secure  exchange  of  data  in  a  standard  fashion. 

OPTIONS  ^ 

— b  Select  ECB  (one  byte  at  a  time)  encryption  mode. 

—f  Suppress  warning  message  when  software  implementation  is  used. 

— k  key  Use  the  encryption  key  specified. 

— B  Selects  software  implementation  for  the  encryption  algorithm. 

Two  standard  encryption  modes  are  supported  by  the  des  program,  Cipher  Block  Chaining  (CBC 
-  the  default)  and  Electronic  Code  Book  (ECB  -  specified  with  -b).  CBC  mode  treats  an  entire 
file  as  a  unit  of  encryption,  i.e.,  if  insertions  or  deletions  are  made  to  the  encrypted  file  then 
decryption  will  not  succeed.  CBC  mode  also  ensures  that  regularities  in  clear  data  do  not 
appear  in  the  encrypted  data.  ECB  mode  treats  each  8  bytes  as  units  of  encryptions,  so  if  parts 
of  the  encrypted  file  are  modified  then  other  parts  may  still  be  decrypted.  Identical  values  of 
clear  text  encrypt  to  identical  values  of  cipher  text. 

The  key  used  for  the  DES  algorithm  is  obtained  by  prompting  the  user  unless  the  -k  key  option 
is  given.  If  the  key  is  an  argument  to  the  des  command,  it  is  potentially  visible  to  users  execut¬ 
ing  pff(l)  or  a  derivative.  To  minimize  this  possibility,  dea  takes  care  to  destroy  the  key  argu¬ 
ment  immediately  upon  entry. 

The  dea  command  attempts  to  use  DES  hardware  for  its  job,  but  will  use  a  software  implementa¬ 
tion  of  the  DES  algorithm  if  the  hardware  is  unavailable.  Normally,  a  warning  message  Is 
printed  if  the  DES  hardware  is  unavailable  since  the  software  is  only  about  l/50th  as  fast.  How¬ 
ever,  the  -f  option  will  suppress  the  warning.  The  -b  option  may  be  used  to  force  use  of  software 
instead  of  hardware  DES. 

The  des  command  reads  from  standard  input  unless  infile  is  specified  and  writes  to  standard  out¬ 
put  unless  outfile  is  given. 

The  following  sections  give  information  required  to  implement  compatible  facilities  in  other 
environments. 

Since  the  CBC  and  ECB  modes  of  DES  require  units  of  8  bytes  to  be  encrypted,  files  being 
encrypted  by  the  des  command  have  1  to  8  bytes  appended  to  them  to  cause  them  to  be  a  multi¬ 
ple  of  8  bytes.  The  last  byte,  when  decrypted,  gives  the  number  of  bytes  (0  to  7)  which  are  to  be 
saved  of  the  last  8  bytes.  The  other  bytes  of  those  appended  to  the  input  are  randomized  before 
encryption.  If,  when  decrypting,  the  last  byte  is  not  in  the  range  of  0  to  7  then  either  the 
encrypted  file  has  been  corrupted  or  an  incorrect  key  was  provided  for  decryption  and  an  error 
message  is  printed. 

The  DES  algorithm  requires  an  8  byte  key  whose  low  order  bits  are  assumed  to  be  odd-parity 
bits.  The  ASCII  key  supplied  by  the  user  is  zero  padded  to  8  bytes  and  the  high  order  bits  are 
set  to  be  odd-parity  bits.  The  DES  algorithm  then  ignores  the  low  bit  "of  each  ASCII  character, 
but  that  bit’s  information  has  been  preserved  in  the  high  bit  due  to  the  parity. 

The  CBC  mode  of  operation  always  uses  an  initial  value  of  all  zeros  for  the  initialization  vector, 
so  the  first  8  bytes  of  a  file  are  encrypted  the  same  whether  in  CBC  or  ECB  mode. 
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FILES 

/dev/des? 

SEE  ALSO 

des(4) 

RESTRICTIONS 

This  program  is  not  available  on  software  shipped  outside  the  U-S. 
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NAME 

df  —  report  free  disk  space  on  file  systems 


SYNOPSIS 

df  [  — i  ]  I  filesystem  ..•  ]  [  file  | 

DESCRIPTION 

D/ displays  the  amount  of  disk  space  occupied  by  currently  mounted  file  systems,  the  amount  of 
used  and  available  space,  and  how  much  of  the  file  system’s  total  capacity  has  been  used.  Used 
without  arguments,  df  produces  something  like: 

%  df 

Filesystem  kbytes  used  avail  capacity  Mounted  on 

/dev/ipOa  7445  4714  1986  70%  / 

/dev/ipOg  42277  35291  2758  93%  /usr 

% 


Note  that  used-havail  is  less  than  the  amount  of  space  in  the  file  system  (kbytes);  this  is  because 
the  system  reserves  a  fraction  of  the  space  in  the  file  system  to  allow  its  file  system  allocation 
routines  to  work  well.  The  amount  reserved  is  typically  about  10%;  this  may  be  adjusted  using 
tunefs{%).  When  all  the  space  on  a  file  system  except  for  this  reserve  is  in  use,  only  the  super- 
user  can  allocate  new  files  and  data  blocks  to  existing  files.  When  a  file  system  is  overallocated  in 
this  way,  df  may  report  that  the  file  system  is  more  than  100%  utilized. 

If  arguments  to  df  are  disk  partitions  (for  example,  /dev/ipOa)  or  UNIX  path  names,  df  produces 
a  report  on  the  file  system  containing  the  named  file.  Thus  *‘df  shows  the  amount  of  space  on 
the  file  system  containing  the  current  directory. 

OPTIONS 

—I  Report  the  number  of  used  and  free  inodes. 

FILES 

/etc/mtab  list  of  currently  mounted  filesystems 
SEE  ALSO 

du(l),  mtab(5),  icheck(8),  quot(8),  tunefs(8) 
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NAME 

diff  —  differential  file  and  directory  comparator 
SYNOPSIS 

dIff  [  -cefh  ]  [  -b  1  filel  file2 
dlff  [  -Dstring  ]  |  j  filel  file2 

diff  [  — 1  !  [  —r  j  I  — •  j  [  I  I  — Sname  ]  [  —cefh  ]  [  -^b  |  dirl  dir2 
DESCRIPTION 

diff  is  a  differential  file  comparator*  When  run  on  regular  files,  and  when  comparing  text  files 
which  differ  during  directory  comparison  (see  the  notes  below  on  comparing  directories),  tells 
what  lines  must  be  changed  in  the  files  to  bring  them  into  agreement.  Except  in  rare  cir¬ 
cumstances,  diff  finds  a  smallest  sufficient  set  of  file  differences.  If  neither  filel  nor  file2  is  a 
directory,  either  may  be  given  as  in  which  case  the  standard  input  is  used.  If  filel  is  a  direc¬ 
tory,  a  file  in  that  directory  whose  file-name  is  the  same  as  the  file-name  of  file2  is  used  (and  vice 
versa). 

There  are  several  options  for  output  format;  the  default  output  format  contains  lines  of  these 
forms: 

nl  a  nS,n4 
nl,n2  d  nS 
nl,n2  c  n8,n4 

These  lines  resemble  ed  commands  to  convert  filel  into  file2.  The  numbers  after  the  letters  per¬ 
tain  to  file2.  In  fact,  by  exchanging  ‘a’  for  *d’  and  reading  backward  one  may  ascertain  equally 
how  to  convert  file2  into  fileL  As  in  ed,  identical  pairs  where  nl  —  n2  or  nS  ^  n4  are  abbrevi¬ 
ated  as  a  single  number. 

Following  each  of  these  lines  come  all  the  lines  that  are  affected  in  the  first  file  flagged  by  *<’, 
then  all  the  lines  that  are  affected  in  the  second  file  flagged  by 

If  both  arguments  are  directories,  diff  sorts  the  contents  of  the  directories  by  name,  and  then 
runs  the  regular  file  diff  program  as  described  above  on  text  files  which  are  different.  Binary  files 
which  differ,  common  subdirectories,  and  files  which  appear  in  only  one  directory  are  listed. 

OPTIONS 

Except  for  — b,  which  may  be  given  with  any  of  the  others,  the  following  options  are  mutually 
exclusive; 

— e  produce  a  script  of  a,  c  and  d  commands  for  the  editor  ed,  which  will  recreate  file2  from 

filel.  In  connection  with  — c,  the  following  shell  program  may  help  maintain  multiple 
versions  of  a  file.  Only  an  ancestral  file  ($1)  and  a  chain  of  version-to-version  ed  scripts 
($2,$3,...)  made  by  diff  need  be  on  hand.  A  ‘latest  version’  appears  on  the  standard  out¬ 
put. 

(shift;  cat  $♦;  echo  ^l,$p')  |  ed  —  $1 

Extra  commands  are  added  to  the  output  when  comparing  directories  with  — e,  so  that 
the  result  is  a  $k{l)  script  for  converting  text  files  which  are  common  to  the  two  direc¬ 
tories  from  their  state  in  dirl  to  their  state  in  dir2, 

— f  produces  a  script  similar  to  that  of  — e,  not  useful  with  ed,  and  in  the  opposite  order. 

— c  produces  a  diff  with  lines  of  context.  The  default  is  to  present  3  lines  of  context  and  may 

be  changed,  (to  10,  for  example),  by  — clO,  With  — c  the  output  format  is  modified 
slightly:  the  output  beginning  with  identification  of  the  files  involved  and  their  creation 
dates  and  then  each  change  is  separated  by  a  line  with  a  dozen  ♦’s.  The  lines  removed 
from  filel  are  marked  with  those  added  to  file2  are  marked  Lines  which  are 
changed  from  one  file  to  the  other  are  marked  in  both  files  with  *!’. 

— h  does  a  fast,  half-hearted  job.  It  works  only  when  changed  stretches  are  short  and  well 
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separated,  but  does  work  on  files  of  unlimited  length. 

Options  for  the  second  form  of  diff  are  as  follows: 

— 

create  a  merged  version  of  filel  and  file2  on  the  standard  output,  with  C  preprocessor 
controls  included  so  that  a  compilation  of  the  result  without  defining  string  is  equivalent 
to  compiling  filel,  while  defining  string  will  yield  file2. 

— b  ignore  trailing  blanks  (spaces  and  tabs);  other  strings  of  blanks  compare  equal. 

Options  when  comparing  directories  are: 

—1  long  output  format;  each  text  file  diff  is  piped  through  pr(l)  to  paginate  it,  other 
differences  are  remembered  and  summarized  after  all  text  file  differences  are  reported. 

— r  apply  diff  recursively  to  common  subdirectories  encountered. 

— B  report  files  which  are  the  same,  which  are  otherwise  not  mentioned. 

—Sname 

starts  a  directory  diff  in  the  middle,  beginning  with  file  name. 

FILES 

/tmp/d????? 

/usr/lib/diffh  for  — h 
/usr/bin/pr 

SEE  ALSO 

cmp(l),  cc(l),  comm(l),  ed(l),  diff3(l) 

DIAGNOSTICS 

Exit  status  is  0  for  no  differences,  1  for  some,  2  for  trouble. 

BUGS 

Editing  scripts  produced  under  the  — e  or  — f  option  are  naive  about  creating  lines  consisting  of  a 
single 

When  comparing  directories  with  the  option  specified,  diff  first  compares  the  files  (as  in  cmp), 
and  then  decides  to  run  the  diff  algorithm  if  they  are  not  equal.  This  may  cause  a  small  amount 
of  spurious  output  if  the  files  then  turn  out  to  be  identical,  because  the  only  differences  are 
insignificant  blank  string  differences. 
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NAME 

diffS  —  3-way  differential  file  comparison 
SYNOPSIS 

difiB  I  — ex3  j  filel  file2  file3 
DESCRIPTION 

DiffS  compares  three  versions  of  a  file,  and  publishes  disagreeing  ranges  of  text  flagged  with  these 
codes: 

all  three  files  differ 
====1  filel  is  different 

====2  files  is  different 

====3  files  is  different 

The  type  of  change  suffered  in  converting  a  given  range  of  a  given  file  to  some  other  is  indicated 
in  one  of  these  ways: 

/ :  nf  a  Text  is  to  be  appended  after  line  number  nl  in  file  f,  where  /*»  1,  2,  or  3. 

f  t  nl  f  nS  c  Text  is  to  be  changed  in  the  range  line  nl  to  line  nS,  If  nl  *=  nS,  the  range 

may  be  abbreviated  to  nl. 

The  original  contents  of  the  range  follows  immediately  after  a  c  indication.  When  the  contents  of 
two  files  are  identical,  the  contents  of  the  lower-numbered  file  is  suppressed. 

Under  the  — e  option,  diffS  publishes  a  script  for  the  editor  erf  that  will  incorporate  into  filel  all 
changes  between  fileS  and  fileS,  i,e,  the  changes  that  normally  would  be  flagged  =====  and 
-^—=3.  Option  —X  (—3)  produces  a  script  to  incorporate  only  changes  flagged  ==== 
(===:=3].  The  following  command  will  apply  the  resulting  script  to  ‘filel’. 

(cat  script;  echo  ^l,$p^)  |  ed  —  filel 

FILES 

/tmp/d3????? 

/usr/Iib/diff3 

SEE  ALSO 

diff(l) 

BUGS 

Text  lines  that  consist  of  a  single  will  defeat  — e* 
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NAME 

domainname  —  set  or  display  name  of  current  domain  system 
SYNOPSIS 

domainname  |  nameofdomain  | 

DESCRIPTION 

With  no  arguments,  domainname  displays  the  name  of  the  current  domain.  The  yellow  pages  use 
the  domain  to  refer  to  a  group  of  hosts. 

Only  the  super-user  can  set  the  domainname  by  giving  an  argument;  this  is  usually  done  in  the 
startup  script  letc/rc.local. 

SEE  ALSO 

getdomainname(2),  setdomaittname(2),  ypinit(8) 
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NAME 

du  —  summarize  disk  usage 
SYNOPSIS 

du  I  —8  I  j  —a  ]  [  name  •••  | 

DESCRIPTION 

Du  gives  the  number  of  kilobytes  contained  in  all  files  and,  recursively,  directories  within  each 
specified  directory  or  file  name.  If  name  is  missing,  (the  current  directory)  is  used. 

A  file  which  has  multiple  links  to  it  is  only  counted  once. 

OPTIONS 

— s  Only  display  the  grand  total. 

—a  Generate  an  entry  for  each  file. 

Entries  are  generated  only  for  each  directory  in  the  absence  of  options. 

EXAMPLE 

Here  is  an  example  of  using  du  in  a  directory.  We  used  the  pwd  command  to  identify  the  direc- 
tory,  then  used  du  to  show  the  usage  of  all  the  subdirectories  in  that  directory.  The  grand  total 
for  the  directory  is  the  last  entry  in  the  display: 

%  pwd 

/usr/henry/misc 

%  du 

5  •/jokes 

33  •/squash 

44  ./tech. papers/lpr. document 

217  ./tech  .papers/ new.manager 

401  ./tech. papers 

144  ./memos 

80  ./letters 

388  ./window 

03  ./messages 

15  ./useful.news 

1211  . 

% 

SEE  ALSO 

df(l),  quot(8) 

BUGS 

Non-directories  given  as  arguments  (not  under  —a  option)  are  not  listed. 

If  there  are  too  many  distinct  linked  files,  du  counts  the  excess  files  multiply. 
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NAME 

echo  -  echo  arguments 
SYNOPSIS 

echo  j  — n  )  j  argument ...  | 

DESCRIPTION 

Echo  writes  its  arguments  on  the  standard  output.  Arguments  must  be  separated  by  spaces  or 
tabs,  and  terminated  by  a  newline. 

Echo  is  useful  for  producing  diagnostics  in  shell  programs  and  for  writing  constant  data  on  pipes. 
If  you  are  using  the  Bourne  Shell  (sA(l)),  you  can  send  diagnostics  to  the  standard  error  file  by 
typing:  ‘echo  ...  1>&2’. 

OPTIONS 

— n  Don’t  add  the  newline  to  the  output. 
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NAME 

ed  —  text  editor 
SYNOPSIS 

ed  [  —  ]  [  — X  ]  [  filename  | 

DESCRIPTION 

Ed  is  the  basic  text  editor  in  the  UNIX  system.  While  ed  is  for  all  practical  purposes  superseded 
by  vif  ed  is  still  used  by  other  system  utilities  such  as  SCCS.  Ed  is  a  line  editor  —  in  general,  you 
must  specify  the  tine  or  lines  on  which  to  perform  the  operation  you  choose  (see  Line  Addressing, 
below,  for  a  discussion  of  how  to  form  line-addresses  for  erf).  You  can  tell  erf  to  perform  various 
operations  on  the  lines.  For  instance,  you  can  print  (display)  lines;  you  can  change  lines;  you  can 
insert  new  lines  into  the  buffer;  you  can  delete  existing  lines;  you  can  move  or  copy  lines  to  a 
different  place  in  the  buffer;  you  can  substitute  character  strings  within  lines.  See  List  of  Opera¬ 
tions,  below,  for  a  guide.  Also,  see  Regular  Expressions  for  string-matching  metacharacters. 

Ed  does  not  directly  change  the  contents  of  a  file  —  when  editing  a  file,  ed  reads  the  contents  of 
the  file  into  a  buffer  or  scratchpad.  All  changes  made  during  an  editing  session  are  made  on  the 
contents  of  this  buffer.  The  copy  must  be  ‘saved’  or  ‘written’  —  using  the  w  (write)  operation  — 
to  save  changes. 

The  command-line  shown  in  the  synopsis  above  invokes  erf.  If  filename  is  given,  erf  reads  a  copy 
of  filename  into  its  buffer  so  that  it  can  be  edited  (simulates  an  e  operation  on  filename). 

Ed  commands  have  a  simple  and  regular  structure:  commands  consists  of  an  optional  line- 
address,  or  two  optional  line-addresses  separated  by  a  comma,  then  a  single  letter  operation, 
optionally  followed  by  some  other  parameter: 

[line-address  ]  Jine-address  j  ]  operation  [  parameter] 

For  example,  T,10p’  means  ‘print  (display)  lines  1  through  10’  (two  line-addresses),  ‘5a’  means 
‘append  after  line  5’  (one  line-address),  and  d  means  ‘delete  the  current  line’  (no  line-address  with 
the  current  line  used  as  default).  Parameter  varies  for  each  operation  —  for  the  move  and 
transfer  operations,  for  example,  it  is  the  line  that  the  addressed  lines  are  to  be  moved  or 
transferred  after.  These  operations  actually  have  three  line-addresses.  For  reading  and  writing 
a  file,  parameter  specifies  the  name  of  the  file  that  is  to  be  read. 

Ed  is  extremely  terse  in  its  interaction  with  the  user  —  erf’s  normal  response  to  just  about  any 
problem  is  simply  a  question  mark  T.  You  get  this  response  when,  for  instance,  erf  can’t  find  a 
specified  line  in  the  buffer,  or  if  a  search  for  a  regular  expression  fails  in  a  substitute  (s)  opera¬ 
tion. 

OPTIONS 

—  Suppress  the  display  of  character  counts  normally  given  by  the  e,  r,  and  w  operations  — 
can  be  used  when  the  standard  input  is  an  editor  script. 

—X  Simulate  an  x  operation  on  the  named  file  before  reading  it  into  the  buffer,  to  handle 
encryption, 

LINE  ADDRESSING 

The  format  of  erf  operations  above  shows  that  an  operation  can  be  preceded  by  one  or  two  line- 
addresses,  both  of  which  are  optional.  If  only  one  line-address  is  specified,  operations  are  per¬ 
formed  on  that  specific  line.  If  two  line-addresses  are  supplied,  erf  operates  on  the  inclusive  range 
of  lines  between  them. 

Line- ad  dr  esses  are  usually  separated  from  each  other  by  a  comma  —  for  instance: 
l,10p 

prints  (displays)  lines  1  thru  10. 
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Line  addresses  may  also  be  separated  by  a  semicolon.  Whereas  the  starting  position  for  line- 
addresses  separated  by  a  comma  is  the  same  place  in  the  buffer,  when  a  line-address  is  followed 
by  a  semicolon,  the  current  line  is  set  to  the  line-address  preceding  the  semicolon  before  any  sub¬ 
sequent  line-addresses  are  interpreted.  For  example: 

/Domaine  Chandon/;//p 

sets  the  current  line  to  the  first  occurrence  of  the  string  ‘Domaine  Chandon’  before  starting  the 
search  for  the  second  occurrence.  This  feature  can  be  used  to  determine  the  starting  line  for  for¬ 
ward  and  backward  searches  (*/*, 

Lines  can  be  accessed  (addressed,  in  ed  terminology)  in  several  ways,  but  the  most  easily  under¬ 
stood  way  of  addressing  lines  is  by  line  number.  Line  numbers  in  ed  are  relative  to  the  start  of 
the  buffer.  In  practice,  addressing  lines  by  number  proves  to  be  the  most  awkward  to  use,  so  ed 
provides  other  mechanisms  for  line-addressing.  Note  that  the  line  numbers  associated  with  lines 
in  the  buffer  are  not  physically  present  with  the  text  of  the  lines  —  they  are  just  an  addressing 
mechanism. 

While  ed  is  working  on  the  buffer,  it  keeps  track  of  the  line  on  which  you  last  performed  some 
operation.  This  line  is  called  the  ‘current  line’.  As  described  below,  you  can  indicate  the  current 
line  by  typing  a  period  character  (•). 

If  you  don’t  specify  a  line  for  an  operation  to  operate  on,  most  ed  operations  work  on  the  line 
addressed  by  the  current  line. 

When  ed  starts  working  on  a  file,  the  current  line  is  positioned  at  the  last  line  in  the  buffer. 
Thereafter,  the  current  line  usually  changes  when  any  operation  is  performed.  In  general,  the 
current  line  sits  at  the  last  line  affected  by  whatever  ed  operation  you  used.  For  instance,  if  you 
print  lines  1  through  10  of  the  buffer,  after  the  lines  are  displayed,  the  current  line  will  be  posi¬ 
tioned  at  line  10. 

Line-addresses  are  constructed  from  elements  as  shown  in  the  list  below.^  Some  special  characters 
are  used  as  a  shorthand  for  certain  line-addresses: 

.  (‘dot’)  addresses  the  current  line. 

$  addresses  the  last  line  of  the  buffer. 

nnn  A  decimal  number  nnn  addresses  the  nnn-th  line  of  the  buffer. 

addresses  the  line  marked  with  the  name  which  must  be  a  lower-case  letter.  Mark 
lines  with  the  k  operation  described  below. 

/regular  expression/ 

A  regular  expression  enclosed  in  slashes  ‘/’  searches  forward  from  the  current  line  and 
stops  at  the  first  line  containing  a  string  that  matches  the  regular  expression.  If  neces¬ 
sary,  the  search  wraps  around  to  the  beginning  of  the  buffer. 

'tregular  expression*t 

A  regular  expression  enclosed  in  question  marks  searches  backward  from  the  current 
line  and  stops  at  the  first  line  containing  a  string  that  matches  the  regular  expression.  If 
necessary  the  search  wraps  around  to  the  end  of  the  buffer. 

addres$±nnn 

An  address  followed  by  a  plus  sign  ‘H-*  or  a  minus  sign  followed  by  a  decimal  number 
specifies  that  line-address  plus  or  minus  the  indicated  number  of  lines.  Plus  is  assumed  if 
no  signs  are  given. 

±address 

An  address  beginning  with  or  ^  is  taken  relative  to  the  current  line;  in  other  words, 
‘—6’  is  understood  to  mean  ‘.—S’. 

addre8s± 

An  address  ending  with  or  adds  or  subtracts  1.  As  a  consequence  of  this  rule  and 
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the  previous  rule,  the  line-address  ’  refers  to  the  line  before  the  current  line.  More¬ 
over,  trailing  ‘V  and  ’  characters  have  cumulative  effect,  so  ‘ ’  refers  to  the  current 

line  less  2. 

To  maintain  compatibility  with  earlier  versions  of  ed,  the  character  ‘"’in  line- addresses 
is  equivalent  to  \ 

Ed  operations  do  not  necessarily  use  line-addresses;  they  may  use  one  or  two.  Operations  which 
don’t  use  line-addresses  regard  the  presence  of  a  line-address  as  an  error.  Operations  which 
accept  one  or  two  line-addresses  assume  default  line-addresses  if  these  are  not  specified.  If  more 
line-addresses  are  given  than  such  an  operation  requires,  the  last  one  or  two  (depending  on  what 
is  accepted)  are  used.  The  second  line-address  of  any  two-address  sequence  must  be  greater  than 
the  first  line-address  —  that  is,  the  second  line  must  follow  the  first  line  in  the  buffer. 


LIST  OF  OPERATIONS 

Ed  operates  in  one  of  two  major  modes:  command  mode  and  text  input  mode.  Ed  always  starts 
up  in  command  mode. 


While  you  are  typing  commands  at  ed,  you  are  in  command  mode.  Some  commands  —  a  for 
append,  c  for  change,  and  !  for  Insert  —  provide  for  adding  new  text  to  the  buffer.  While  erf  is 
accepting  new  text,  you  are  in  text  input  mode.  You  exit  from  text  input  mode  by  typing  a 
period  alone  at  the  beginning  of  a  line.  Ed  then  reverts  to  command  mode.  For  example,  here 
is  a  very  short  illustration  of  command  mode  versus  text  mode: 


example% 

42 

i,$p 


ed  wlnellst  (tell  ed  to  edit  a  file  called  unnelist) 

(erf  states  there  are  42  characters  m  the  file) 
(m  command  mode  —  tell  ed  to  print  all  lines) 


1978  Chateau  Chunder 

1979  Redeye  Canyon 

a 

1980  Doomsday  Special 

• 

P 

1980  Doomsday  Special 


(m  command  mode  —  tell  ed  to  append  text) 

(text  input  mode  —  add  a  new  line) 

(period  ends  text  input  mode) 

(back  in  command  mode  —  prmf  last  line  entered) 


w 

65 

q 

example% 


(command  mode  —  write  the  file) 

(ed  displays  the  number  of  characters  written) 
(command  mode  —  quit  the  edit  session) 
(back  in  the  Shell) 


If  you  interrupt  ed,  it  displays  ^interrupted’  and  returns  to  command  mode. 


a  Append  Text, 

Reads  the  text  entered  in  input  mode  and  appends  it  to  the  buffer  after  the  addressed 
line,  a  accepts  one  line-address  —  default  line-address  is  the  current  line.  The  new 
current  line  is  the  last  line  input,  or  at  the  addressed  line  if  no  text  is  entered.  Address 
‘0’  is  a  valid  place  to  append  text,  in  which  case  text  is  placed  at  the  beginning  of  the 
buffer. 


c  Change  Lines. 

Deletes  the  addressed  lines,  then  accepts  input  text  which  replaces  these  lines,  c  accepts 
two  line-addresses  —  default  line-address  is  the  current  line.  The  current  line  is  left  on 
the  last  line  input,  or  at  the  line  preceding  the  deleted  lines  if  no  text  is  entered. 

d  Delete  Lines, 

Delete  the  addressed  lines  from  the  buffer,  d  accepts  two  line-addresses  —  default  line- 
address  is  the  current  line.  The  line  originally  after  the  last  line  deleted  becomes  the 
current  line;  if  the  lines  deleted  were  originally  at  the  end,  the  new  last  line  becomes  the 
current  line. 


e  filename  Edit  a  file. 
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Deletes  the  entire  contents  of  the  buffer,  and  then  reads  in  the  named  file,  e  sets  the 
current  line  to  the  last  line  of  the  buffer,  and  reports  the  number  of  characters  read  into 
the  buffer,  e  remembers  filename  for  possible  use  as  a  default  file  name  in  a  subsequent 
r  or  w  operations.  If  no  filename  is  given,  the  remembered  filename  is  used,  e  displays  a 
f  if  the  buffer  has  not  been  written  out  since  the  last  change  made  —  a  second  e  opera¬ 
tion  says  you  really  mean  it, 

E  filename 

Same  as  c,  but  will  silently  allow  you  to  quit  an  editing  session  without  warning  you  if 
you  have  not  written  your  file,  e,  on  the  other  hand,  reminds  you  to  save  your  changes 
if  you  have  altered  the  buffer  at  all. 

t  filename  Display  Remembered  Filename. 

Display  the  currently  ‘remembered  filename’.  If  filename  is  given,  the  currently  ‘remem¬ 
bered  filename’  is  changed  to  filename. 

^/regular  expression! operation 

This  is  the  global  operation:  perform  operation  list  on  all  lines  in  the  range  of  line- 
addresses  containing  regular  expression,  g  accepts  two  line- ad  dr  esses  —  default  is  all 
lines  in  the  buffer.  Also  see  the  v  operation,  which  inverts  the  sense  of  regular  expres¬ 
sion. 

If  your  operation  list  actually  takes  up  more  than  a  single  line,  you  must  end  every  line 
except  the  last  (the  true  ‘end’  of  the  global  operation)  with  an  escape  character,  For 
example,  if  you  want  to  substitute  ‘jimjams’  for  ‘frammis’,  then  append  several  lines  of 
text  to  every  line  containing  the  string  ‘widget’  and  print  those  lines,  you  would  type  this 
sequence: 

g/widget/s/frammis/jimjams/\ 

a\ 

new  line  of  text\ 
another  new  line  of  text\ 

A 

p 

Note  that  the  a,  1,  and  c  operations,  which  put  ed  in  input  mode,  are  permitted  in  the 
operation  list;  the  final  •  terminating  input  may  be  omitted  if  it  is  the  last  line  of  the  opera¬ 
tion  list.  The  g  and  v  operations  are  not  permitted  in  the  operation  list. 

I  Insert  Text. 

Insert  lines  of  text  into  the  buffer  before  the  addressed  line.  I  accepts  one  line-address  — 
default  line-address  is  the  current  line.  The  current  line  is  placed  at  the  last  line  input;  if 
no  text  is  input,  the  current  line  is  left  at  the  line  before  the  addressed  line,  i  differs  from  a 
only  in  the  placement  of  the  text. 

J  Join  Lines. 

Joins  the  addressed  lines  into  a  single  line;  intermediate  newlines  simply  disappear.  J 
accepts  two  line-addresses  —  default  is  the  current  line  and  the  following  line.  The  current 
line  is  placed  at  the  resulting  line. 

kx  Mark  Line. 

Marks  the  addressed  line  with  name  x  (the  name  must  be  a  lower-case  letter).  The  line- 
address  form  'ar  then  addresses  this  line,  k  accepts  one  line-address  —  default  line-address 
is  the  current  line. 

I  Display  Non-printing  Characters. 

Displays  non-graphic  characters  in  the  addressed  lines  such  that  they  are  displayed  in  two- 
digit  octal,  and  long  lines  are  folded.  1  accepts  two  line-addresses  —  default  line-address  is 
the  current  line.  1  may  be  placed  on  the  same  line  after  any  non-I/O  operation. 
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marfrfres?  Move  lines. 

Reposition  the  addressed  lines  after  the  line- ad  dressed  by  address,  m  accepts  two  line- 
addresses  to  specify  the  range  of  lines  to  be  moved  —  default  line-address  is  the  current 
line.  The  last  of  the  moved  lines  becomes  the  current  line. 

p  Print  (display)  Lines. 

Displays  the  addressed  lines,  p  accepts  two  line-addresses  —  default  line-address  is  the 
current  line.  The  current  line  is  placed  at  the  last  line  printed,  p  may  be  placed  on  the 
same  line  after  any  non-I/O  operation. 

P  Synonym  for  p. 

q  Quit  Edit  Session. 

Exit  from  the  editing  session.  Note,  however,  that  the  buffer  is  not  automatically  written 
out  (do  a  ‘w’  to  write  if  you  want  to  save  your  changes).  Ed  warns  you  once  if  you  haven’t 
saved  your  file  —  a  second  q  says  you  really  mean  it. 

Q  Same  as  q,  but  you  don’t  get  any  warning  if  you  haven’t  previously  written  out  the  buffer, 
r  filename  Read  from  file. 

Reads  the  contents  of  filename  into  the  buffer  after  the  addressed  line.  If  filename  is  not 
given,  the  'remembered  filename’,  if  any,  is  used  (see  e  and  f).  r  accepts  one  line-address  — 
default  line-address  is  If  line-address  ‘0’  is  used,  r  reads  the  file  in  at  the  beginning  of 
the  buffer.  If  the  read  is  successful,  r  displays  the  number  of  characters  read  in.  The 
current  line  is  left  at  the  last  line  read  in  from  the  file. 

b/ regular  expression / replacement  string f  or, 
regular  expression f  replacement  string 

Substitute  the  replacement  string  for  the  first  occurrence  of  regular  expression  on  each  line 
where  the  regular  expression  occurs.  In  the  first  form  of  the  i  operation,  only  the  first 
occurrence  of  the  matched  string  on  each  line  is  replaced.  If  you  use  the  g  (global)  suffix, 
all  occurrences  of  the  regular  expression  are  replaced  in  the  line.  Keep  the  g  suffix  of  the  a 
operation  distinct  from  the  g  operation  itself  —  they  are  completely  different.  8  accepts 
two  line-addresses  to  delimit  the  range  of  lines  within  which  the  substitutions  should  be 
done  —  default  line-address  is  the  current  line.  The  current  line  is  left  at  the  last  line  sub¬ 
stituted. 

Special  Characters: 

Any  punctuation  character  may  be  used  instead  of  '/’  to  delimit  the  regular  expres¬ 
sion  and  the  replacement  string. 

An  ampersand  appearing  in  the  replacement  string  is  replaced  by  the  string 
matching  the  regular  expression.  The  special  meaning  of  in  this  context  may  be 
suppressed  by  preceding  it  by 

The  characters  \n  where  n  is  a  digit,  are  replaced  by  the  text  matched  by  the  n-th 
regular  subexpression  enclosed  between  '\(’  and  When  nested,  parenthesized 
subexpressions  are  present,  n  is  determined  by  counting  occurrences  of  '\(’  starting 
from  the  left.  Lines  may  be  split  by  substituting  new-line  characters  into  them. 
The  new-line  in  the  replacement  string  must  be  escaped  by  preceding  it  by 

taddress  Transfer  Lines. 

Transfers  a  copy  of  the  addressed  lines  to  after  line  address,  transfer  is  like  move,  but  It 
makes  copies  of  the  lines,  leaving  the  original  text  where  it  was.  t  accepts  two  line- 
addresses  preceeding  the  operation  letter  —  default  line-address  is  default.  The  current 
line  is  left  on  the  last  line  of  the  copy,  'O’  is  a  legal  line-address  for  the  destination. 

u  Undo.  Undo  previous  substitute. 

undo  undoes  the  effect  of  the  the  last  substitute  operation,  providing  that  the  current  line 
has  not  been  moved  since  the  substitute  operation. 
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v/regular  expression/operation  list 

Like  a  negative  of  the  global  operation,  g:  perform  operation  list  on  all  lines  except  those 
containing  regular  expression,  v  accepts  two  line-addresses  —  default  is  all  lines  in  the  file. 

w  Write  Lines. 

Write  the  addressed  lines  from  the  buffer  into  the  file  specified  by  the  ‘remembered 
filename*,  w  accepts  two  line-addresses  —  default  is  all  lines  in  the  file.  The  current  line  is 
unchanged.  If  the  write  is  successful,  ed  displays  the  number  of  characters  written. 

w  filename  Write  Lines. 

Write  the  addressed  lines  into  filename.  Filename  is  created  if  it  does  not  already  exist. 
Filename  becomes  the  ‘remembered  filename*  (see  the  e  and  f  operations),  w  accepts  two 
line-addresses  —  default  is  all  lines  in  the  file.  The  current  line  is  unchanged.  If  the  write 
is  successful,  ed  displays  the  number  of  characters  written. 

W  filename 

Same  as  w,  but  appends  the  addressed  lines  to  the  named  file  instead  of  overwriting  the 
file.  W  accepts  two  line-addresses  —  default  is  all  lines  in  the  file. 

X  Encrypt  File. 

When  X  is  used,  ed  demands  a  key  string  from  the  standard  input.  Later  r,  e,  and  w 
operations  will  encrypt  and  decrypt  the  text  with  this  key  by  the  algorithm  of  crypf(l).  An 
explicitly  empty  key  turns  off  encryption. 

=  Display  Line  Number. 

Display  the  line  number  of  the  addressed  line.  =  accepts  one  line-address  —  default  line- 
address  is  $.  The  current  line  is  unchanged  by  this  operation. 

!<8hell  command  > 

The  remainder  of  the  line  after  the  V  is  sent  to  5^(1)  to  be  interpreted  as  a  shell  command. 
The  current  line  is  unchanged. 

addres^<newnne> 

Display  the  addressed  line.  If  you  type  a  line-address  and  type  RETURN,  ed  displays  the 
addressed  line.  If  you  simply  type  RETURN,  the  line  following  the  current  line  is  displayed 
(equivalent  to  ‘•H-lp’).  This  is  useful  for  stepping  through  text. 

REGULAR  EXPRESSIONS 

Ed  supports  a  limited  form  of  regular  expression  notation.  A  regular  expression  (also  known  as  a 
pattern)  specifies  a  set  of  strings  of  characters  —  such  as  ‘any  string  containing  digits  5  through 
9*  or  ‘only  lines  containing  uppercase  letters’.  A  member  of  this  set  of  strings  is  said  to  be 
matched  by  the  regular  expression.  Regular  expressions  or  patterns  are  used  to  address  lines  in 
the  buffer  (see  Line  Addressing,  above),  and  also  for  selecting  strings  to  be  substituted  in  the  s 
(substitute)  operation  described  previously. 

An  empty  regular  expression,  indicated  by  two  regular  expression  delimiters  in  a  row,  stands  for 
a  copy  of  the  last  regular  expression  encountered. 

Any  given  regular  expression  matches  the  the  longest  among  the  leftmost  matches  in  a  line. 

In  the  following  specification  for  regular  expressions,  the  notation  C  stands  for  any  single  ordinary 
character,  where  a  character  is  anything  except  a  newline  character, 

C  any  ordinary  character  except  a  special  character  matches  itself.  Special  characters  are 
the  delimiters  that  actually  surround  the  regular  expression,  plus  \  (the  escape  charac¬ 
ter),  [  (the  opening  bracket  for  a  character  class  as  described  below),  •  (period  which 
matches  any  single  character),  and  sometimes  the  ♦  (closure)  "  and  $  characters.  If  you 
want  a  literal  occurrence  of  one  of  these  special  characters  you  must  escape  them  with 
the  \  character. 

"  at  the  very  start  of  the  regular  expression  constrains  the  match  to  the  beginning  of  the 
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line.  A  match  of  this  type  is  called  an  ‘anchored  match’  because  it  is  ‘anchored*  to  a 
specific  place  in  the  line.  The  ^  character  loses  its  special  meaning  if  it  appears  in  any 
position  other  than  at  the  very  start  of  the  regular  expression. 

$  at  the  very  end  of  the  regular  expression  constrains  the  match  to  the  end  of  the  line.  A 
match  of  this  type  is  called  an  ‘anchored  match’  because  it  is  ‘anchored*  to  a  specific 
place  in  the  line.  The  $  character  loses  its  special  meaning  if  it  appears  in  any  position 
other  than  at  the  very  end  of  the  regular  expression. 

.  (period)  matches  any  single  character  except  a  newline  character. 

A  string  of  characters  enclosed  in  brackets  matches  any  one  of  the  characters  in  the 
brackets.  For  example,  [abcxyz]  matches  any  single  character  from  the  set  ‘abcxyz’.  If 
the  first  character  inside  the  bracket  is  a  the  string  matches  any  character  not  inside 
the  brackets.  For  instance,  ("456787]  matches  any  character  except  ‘45678*.  You  can 
use  a  shorthand  notation  to  refer  to  an  inclusive  range  of  characters:  a— b.  Such  a 
bracketed  string  of  characters  is  known  as  a  character  class. 

When  two  regular  expressions  are  concatenated,  they  match  the  leftmost  and  then  the 
longest  possible  string  that  can  be  divided  with  the  first  part  of  the  string  matching  the 
first  regular  expression,  followed  by  the  second  string  matching  the  second  regular 
expression. 

♦  Any  regular  expression  followed  by  *  matches  a  sequence  of  0  or  more  matches  of  the 
regular  expression.  Such  a  pattern  is  called  a  closure.  For  example:  [a*-s][a— z]* 
matches  any  string  of  one  or  more  lower  case  letters. 

\{regular  expression\^ 

The  regular  expression  within  the  \(  and  \)  brackets  essentially  ‘remembers’  whatever 
the  regular  expression  matches.  This  provides  a  mechanism  for  extracting  parts  of 
strings.  There  can  be  up  to  nine  such  partial  matches  in  a  string.  Parenthesized  regular 
expressions  can  be  nested. 

\n  where  n  is  in  the  range  1  thru  9,  matches  a  copy  of  the  string  that  the  bracketed  regular 
expression  beginning  with  the  nth  \(  matched,  as  described  in  the  previous  paragraph  on 
matching  parts  of  strings.  When  nested,  parenthesized  subexpressions  are  present,  n  is 
determined  by  counting  occurrences  of  \(  starting  from  the  left. 

Regular  expressions  are  used  in  line-addresses  to  specify  lines  and  in  one  operation  (see  s  for  sub¬ 
stitute  above)  to  specify  a  portion  of  a  line  which  is  to  be  replaced.  If  it  is  desired  to  use  one  of 
the  regular  expression  metacharacters  as  an  ordinary  character,  that  character  may  be  preceded 
by  ‘\*.  This  also  applies  to  the  character  bounding  the  regular  expression  (often  ‘/*)  and  to  \ 
itself. 

FILES 

/tmp/e* 

ed.hup:  work  is  saved  here  if  telephone  hangs  up 

SEE  ALSO 

Using  the  ed  Line  Editor  in  Editing  and  Text  Processing  on  the  Sun  Workstation. 

crypt(l)  encode  and  decode 

ex(l)  extended  line  editor  (part  of  vi) 

sed(l)  stream  editor 

vi(l)  visual  (display)  editor 

BUGS 

The  1  operation  mishandles  DEL. 

The  undo  operation  removes  marks  from  affected  lines. 

Because  0  is  an  illegal  line-address  for  a  w  operation,  it  is  not  possible  to  create  an  empty  file 
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with  td.  Use  ca<(l)  to  create  an  empty  file. 

RESTRICTIONS 

Some  size  limitations;  512  characters  per  line,  256  characters  per  global  command  list,  64  charac¬ 
ters  per  file  name,  and  128K  characters  in  the  temporary  file.  Since  each  line  uses  two  bytes  of 
memory,  the  limit  on  the  number  of  lines  should  not  be  exceeded  in  practice. 

When  reading  a  file,  erf  discards  ASCTI NUL  characters  and  all  characters  after  the  last  newline,  erf 
refuses  to  read  files  containing  non-ASCll  characters. 

The  encryption  facilities  of  erf  are  not  available  on  software  shipped  outside  the  U.S. 
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NAME 

eqn,  neqn,  checkeq  —  typeset  mathematics 
SYNOPSIS 

eqn  [  —day  ]  |  — pn  ]  [  — ■«  )  j  — fn  ]  (  filename  |  . . . 
neqn  |  filename  j  . .. 
checkeq  [  filename  ]  . . . 

DESCRIPTION 

Eqn  (and  neqn)  are  language  processors  to  assist  in  describing  equations.  Eqn  is  a  preprocessor 
for  troff{l)  and  is  intended  for  devices  that  can  print  trojBTs  output.  Neqn  is  a  preprocessor  for 
Rrc^(l)  and  is  intended  for  use  with  terminals.  Usage  is  almost  always: 
tutorial%  eqn  file  . . .  |  troff 
tutorial^  neqn  file  . . .  J  nroff 

If  no  files  are  specified,  eqn  and  neqn  read  from  the  standard  input.  A  line  beginning  with  ‘.EQ’ 
marks  the  start  of  an  equation;  the  end  of  an  equation  is  marked  by  a  line  beginning  with  ‘.EN’. 
Neither  of  these  lines  is  altered,  so  they  may  be  defined  in  macro  packages  to  get  centering, 
numbering,  etc.  It  is  also  possible  to  set  two  characters  as  ‘delimiters’;  subsequent  text  between 
delimiters  is  also  treated  as  eqn  input. 


Checkeq  reports  missing  or  unbalanced  delimiters  and  .EQ/.EN  pairs. 

OPTIONS 

—dxy  Set  equation  delimiters  may  be  set  to  characters  x  and  y  with  the  command-line  argu¬ 
ment.  The  more  common  way  to  do  this  is  with  ‘delim  xy’  between  .EQ  and  .EN.  The 
left  and  right  delimiters  may  be  identical.  Delimiters  are  turned  off  by  ‘delim  off’  appear¬ 
ing  in  the  text.  All  text  that  is  neither  between  delimiters  nor  between  .EQ  and  .EN  is 
passed  through  untouched. 

— pn  Reduce  subscripts  and  superscripts  by  n  point  sizes  from  the  previous  size.  In  the 
absence  of  the  — p  option,  subscripts  and  superscripts  are  reduced  by  3  point  sizes  from 
the  previous  size. 


— sn  Change  point  size  to  n  globally  in  the  document.  The  point  size  can  also  be  changed  glo¬ 

bally  in  the  body  of  the  document  by  using  the  gsize  directive. 

— frt  Change  font  to  n  globally  in  the  document.  The  font  can  also  be  changed  globally  in  the 

body  of  the  document  by  using  the  gfont  directive. 


EQN  LANGUAGE 

Tokens  within  eqn  are  separated  by  spaces,  tabs,  newlines,  braces,  double  quotes,  tildes  or 
circumflexes.  Braces  {}  are  used  for  grouping;  generally  speaking,  anywhere  a  single  character 
like  X  could  appear,  a  complicated  construction  enclosed  in  braces  may  be  used  instead.  Tilde  (') 
represents  a  full  space  in  the  output,  circumflex  (")  half  as  much. 

Subscripts  and  superscripts ^are  produced  with  the  keywords  sub  ajd^up.  Thus  x  sub  i  makes 
x^,  a  sub  i  sup  8  produces  o,  ,  and  e  sup  {x  sup  S  +  y  sup  S}  gives  e*  . 


0 

Fractions  are  made  with  over:  a  over  b  yields  . 

b 

sqrt  makes  square  roots;  1  over  sqrl  {ax  sup  2  -hJi-hc)  results  in 


1 


ax  +bx+c 


n 


The  keywords  from  and  to  introduce  lower  and  upper  limits  on  arbitrary  things: 
made  with  lim  from  {n— >  inf  }  sum  from  0  to  n  x  sub  i. 


lim 

n—KX) 

0 


is 
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Left  and  right  brackets,  braces,  etc.,  of  the  right  height  are  made  with  left  and  right:  left  [  x 

2  -| 

2  y_ 

sup  S  ^  y  sup  S  over  alpha  right  j  produces  a?  +  =*  1.  The  right  clause  is  optional. 

Of  • 

Legal  characters  after  left  and  right  are  braces,  brackets,  bars,  c  and  f  for  ceiling  and  floor,  and 
for  nothing  at  all  (useful  for  a  right-side-only  bracket). 

Vertical  piles  of  things  are  made  with  pile,  Iplle,  cplle,  and  rpile:  pile  {a  above  b  above  c}  pro- 
a 

duces  There  can  be  an  arbitrary  number  of  elements  in  a  pile.  Ipile  left-justifies,  pile  and 
c 

cpile  center,  with  different  vertical  spacing,  and  rpile  right  justifies. 

Matrices  are  made  with  matrix:  matrix  {  Icol  {  z  sub  %  above  y  sub  S  }  ccol  {  1  above  2}}  pro- 

duces  .  In  addition,  there  is  rcol  for  a  right-justified  column. 

1/2  2 

Diacritical  marks  are  made  with  dot,  dotdot,_hat,  tilde,  bar,  vec,  dyad,  and  under:  x  dot  ^ 
f(t)  bar  is  y  datdot  bar  n  under  is  y  -  n,  and  x  vec  ^  dyad  is  T  =  IT* 

Sizes  and  font  can  be  changed  with  size  n  or  size  ±n,  roman,  Italic,  bold,  and  font  n.  Size 
and  fonts  can  be  changed  globally  in  a  document  by  gslze  n  and  gfont  n,  or  by  the  command¬ 
line  arguments  — sn  and  — fn. 

Successive  display  arguments  can  be  lined  up.  Place  mark  before  the  desired  lineup  point  in  the 
first  equation;  place  lineup  at  the  place  that  is  to  line  up  vertically  in  subsequent  equations. 

Shorthands  may  be  defined  or  existing  keywords  redefined  with  define; 
define  thing  %  replacement  % 

defines  a  new  token  called  thing  which  will  be  replaced  by  replacement  whenever  it  appears 
thereafter.  The  %  may  be  any  character  that  does  not  occur  in  replacement 

Keywords  like  sum  (J]),  i^l  (/),  and  shorthands  like  >=  (>),  — >  (— ^),  and  !=  {^)  are 

recognized,  Greek  letters  are  spelled  out  in  the  desired  case,  as  in  alpha  or  GAMMA,  Mathemat¬ 
ical  words  like  sin,  cos,  log  are  made  Roman  automatically.  troff{l)  four-character  escapes  like 
\(bu  (•)  can  be  used  anywhere.  Strings  enclosed  in  double  quotes  are  passed  through 
untouched;  this  permits  keywords  to  be  entered  as  text,  and  can  be  used  to  communicate  with 
troff  when  all  else  fails. 

SEE  ALSO 

troff(l),  tbl(l),  ms(7),  eqnchar(7) 

Typesetting  Mathematics  with  'egn^and 

Formatting  Documents  with  *nroff*  and  *troff* 

in  Editing  and  Text  Processing  on  the  Sun  Workstation, 

BUGS 

To  embolden  digits,  parens,  etc,,  it  is  necessary  to  quote  them,  as  in  *bold 


120 


Last  change:  1  February  1985 


Sun  Release  2.0 


ERROR(l) 


USER  COMMANDS 


ERROR(l) 


NAME 

error  analyze  and  disperse  compiler  error  messages 
SYNOPSIS 

error  |  — n  [  |  — s  ]  |  — q  ]  [  — v  ]  (  — t  auffixUst  j  [  —I  ignorefile  |  |  name  j 
DESCRIPTION 

Error  analyzes  error  messages  produced  by  a  number  of  compilers  and  language  processors.  It 
replaces  the  painful,  traditional  methods  of  scribbling  abbreviations  of  errors  on  paper,  and  per¬ 
mits  error  messages  and  source  code  to  be  viewed  simultaneously. 

Error  looks  at  error  messages,  either  from  the  specified  file  name  or  from  the  standard  input, 
and: 

•  Determines  which  language  processor  produced  each  error  message, 

•  Determines  the  file  name  and  line  number  of  the  erroneous  line,  and, 

•  Inserts  the  error  message  into  the  source  file  immediately  preceding  the  erroneous  line. 

Error  messages  which  can’t  be  categorized  by  language  processor  or  content  are  not  inserted  into 
any  file,  but  are  sent  to  the  standard  output.  Error  touches  source  files  only  after  all  input  has 
been  read. 

Options  are  explained  later  on  in  this  manual  entry. 

Error  is  intended  to  be  run  with  its  standard  input  connected  via  a  pipe  to  the  error  message 
source.  Some  language  processors  put  error  messages  on  their  standard  error  file;  others  put 
their  messages  on  the  standard  output.  Hence,  both  error  sources  should  be  piped  together  into 
error.  For  example,  when  using  the  cah  syntax, 

tutoriaI%  make  — s  lint  j&  error  — q  — v 

will  analyze  all  the  error  messages  produced  by  whatever  programs  make  runs  when  making  lint. 

Error  knows  about  the  error  messages  produced  by:  make,  cc,  cpp,  ccom,  as.  Id,  lint,  pi,  pc,  and 
/77.  For  all  languages  except  Pascal,  error  messages  are  restricted  to  one  line.  Some  error  mes¬ 
sages  refer  to  more  than  one  line  in  more  than  one  file,  in  which  case  error  duplicates  the  error 
message  and  inserts  it  at  all  of  the  places  referenced. 

Error  does  one  of  six  things  with  error  messages. 
synchronize 

Some  language  processors  produce  short  errors  describing  which  file  they  are  processing. 
Error  uses  these  to  determine  the  file  name  for  languages  that  don’t  include  the  file  name 
in  each  error  message.  These  synchronization  messages  are  consumed  entirely  by  error, 

discard  Error  messages  from  lint  that  refer  to  one  of  the  two  lint  libraries,  /usr/lib/llib-lc  and 
/usr/lib/llib-port  are  discarded,  to  prevent  accidently  touching  these  libraries.  Again, 
these  error  messages  are  consumed  entirely  by  error, 

nullify  Error  messages  from  lint  can  be  nullified  if  they  refer  to  a  specific  function,  which  is 
known  to  generate  diagnostics  which  are  not  interesting.  Nullified  error  messages  are  not 
inserted  into  the  source  file,  but  are  written  to  the  standard  output.  The  names  of  func¬ 
tions  to  ignore  are  taken  from  either  the  file  named  .errorrc  in  the  user’s  home  directory, 
or  from  the  file  named  by  the  —1  option.  If  the  file  does  not  exist,  no  error  messages  are 
nullified.  If  the  file  does  exist,  there  must  be  one  function  name  per  line. 

not  file  specific 

Error  messages  that  can’t  be  intuited  are  grouped  together,  and  written  to  the  standard 
output  before  any  files  are  touched.  They  are  not  inserted  into  any  source  file. 

file  specific 

Error  messages  that  refer  to  a  specific  file  but  to  no  specific  line  are  written  to  the  stan¬ 
dard  output  when  that  file  is  touched. 
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true  errors 

Error  messages  that  can  be  intuited  are  candidates  for  insertion  into  the  file  to  which 
they  refer. 

Only  true  error  messages  are  inserted  into  source  files.  Other  error  messages  are  consumed 
entirely  by  error  or  are  written  to  the  standard  output.  Error  inserts  the  error  messages  into  the 
source  file  on  the  line  preceeding  the  line  number  in  the  error  message.  Each  error  message  is 
turned  into  a  one  line  comment  for  the  language,  and  is  internally  flagged  with  the  string  *###* 
at  the  beginning  of  the  error,  and  *%%%’  at  the  end  of  the  error.  This  makes  pattern  searching 
for  errors  easier  with  an  editor,  and  allows  the  messages  to  be  easily  removed.  In  addition,  each 
error  message  contains  the  source  line  number  for  the  line  the  message  refers  to.  A  reasonably 
formatted  source  program  can  be  recompiled  with  the  error  messages  still  in  it,  without  having 
the  error  messages  themselves  cause  future  errors.  For  poorly  formatted  source  programs  in  free 
format  languages,  such  as  C  or  Pascal,  it  is  possible  to  insert  a  comment  into  another  comment, 
which  can  wreak  havoc  with  a  future  compilation.  To  avoid  this,  format  the  source  program  so 
there  are  no  language  statements  on  the  same  line  as  the  end  of  a  comment. 

OPTIONS 

— n  Do  not  touch  any  files;  all  error  messages  are  sent  to  the  standard  output. 

— q  Error  asks  whether  the  file  should  be  touched.  A  ‘y’  or  'n’  to  the  question  is  necessary  to 
continue.  Absence  of  the  — q  option  implies  that  all  referenced  files  (except  those  refering  to 
discarded  error  messages)  are  to  be  touched. 

—V  After  all  files  have  been  touched,  overlay  the  visual  editor  vi  with  it  set  up  to  edit  all  files 
touched,  and  positioned  in  the  first  touched  file  at  the  first  error.  If  vi  can’t  be  found,  try 
ex  or  ed  from  standard  places. 

— t  Take  the  following  argument  as  a  suffix  list.  Files  whose  suffices  do  not  appear  in  the  suffix 
list  are  not  touched.  The  suffix  list  is  dot  seperated,  and  wildcards  work.  Thus  the 
suffix  list: 

".c.y.f*.h" 

allows  error  to  touch  files  ending  with  ‘,c’,  ‘.f+’  and  \y\ 

—8  Print  out  statistics  regarding  the  error  categorization.  Not  too  useful. 

Error  catches  interrupt  and  terminate  signals,  and  if  in  the  insertion  phase,  will  orderly  terminate 
what  it  is  doing. 

FILES 

"/.errorrc 
/dev/tty 

BUGS 

Opens  the  teletype  directly  to  do  user  querying. 

Source  files  with  links  make  a  new  copy  of  the  file  with  only  one  link  to  it. 

Changing  a  language  processor’s  format  of  error  messages  may  cause  error  to  not  understand  the 
error  message. 

Error,  since  it  is  purely  mechanical,  will  not  filter  out  subsequent  errors  caused  by  ‘floodgating’ 
initiated  by  one  syntactically  trivial  error.  Humans  are  still  much  better  at  discarding  these 
related  errors. 

Pascal  error  messages  belong  after  the  lines  affected  (error  puts  them  before).  The  alignment  of 
the  ‘j’  marking  the  point  of  error  is  also  disturbed  by  error. 

Error  was  designed  for  work  on  CRT’s  at  reasonably  high  speed.  It  is  less  pleasant  on  slow  speed 
terminals,  and  has  never  been  used  on  hardcopy  terminals. 


function  names  to  ignore  for  lint  error  messages 
user’s  teletype 
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NAME 

ex,  edit  —  text  editor 
SYNOPSIS 

1  —  1  I  1  I  I  I  1  !  +command  |  1  — v  ]  [  — x  ]  (  — wn»n  ]  [  — I  ]  . . . 

edit  [  ex  options  | 

DESCRIPTION 

Ex  is  the  root  of  a  family  of  editors  which  includes  erftl(l),  ex,  and  Display  based  editing  is 
the  focus  of  vi.  Most  users  will  in  fact  use  vi  as  the  principal  interface  to  the  system  rather  than 
ex. 

OPTIONS 

—  supress  all  interactive  feedback  to  the  user  —  useful  for  processing  ex  scripts  in  shell 
files. 

— R  edit  the  file  in  read-only  state. 

— r  recover  the  indicated  files  after  a  crash. 

— t  tag  edit  the  file  containing  the  tag  tag.  A  tags  database  must  have  been  built  previously 
using  the  command. 

-^command 

start  the  editing  session  by  executing  command. 

—V  start  up  in  display  editing  state  using  w(l).  You  can  achieve  the  same  effect  by  simply 
typing  the  vi  command  itself. 

—X  prompt  for  a  key  to  be  used  in  encrypting  the  file  being  edited. 


— wnnn 

set  the  default  window  (number  of  lines  on  your  terminal)  to  nnn —  this  is  useful  if  you 
are  dialling  into  the  system  over  a  slow  ’phone  line. 

“-I  set  up  for  editing  LISP  programs. 

DOCUMENTATION 

The  document  Edit:  A  tutorial  provides  a  comprehensive  introduction  to  edit  assuming  no  previ¬ 
ous  knowledge  of  computers  or  the  UNIX  system. 

The  Ex  Reference  Manual  —  Version  S.5  is  a  comprehensive  and  complete  manual  for  the  com¬ 
mand  mode  features  of  ex,  but  you  cannot  learn  to  use  the  editor  by  reading  it.  For  an  introduc¬ 
tion  to  more  advanced  forms  of  editing  using  the  command  mode  of  ezsee  the  editing  documents 
written  by  Brian  Kernighan  for  the  editor  ed;  the  material  in  the  introductory  and  advanced 
documents  works  also  with  ex. 


An  Introduction  to  Display  Editing  xvith  Vi  introduces  the  display  editor  uiand  provides  reference 
material  on  vi.  These  documents  can  be  found  in  the  Editing  and  Text  Processing  Manual.  In 
addition,  the  Vi  Quick  Reference  card  summarizes  the  commands  of  ui  in  a  useful,  functional 
way,  and  is  useful  with  the  Introduction. 


FILES 

/usr  /lib /exT.Tstrings 
/usr/lib/ex?.?recover 
/usr /lib/ex?, ?preserve 
/etc/termcap 
~/.exrc 

/tmp/Exnnnnn 

/tmp/Rxnunnn 

/usr/preserve 


error  messages 

recover  command 

preserve  command 

describes  capabilities  of  terminals 

editor  startup  file 

editor  temporary 

named  buffer  temporary 

preservation  directory 
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SEE  ALSO 

awk(l),  ed(l),  grep(l),  sed(l),  grep(l),  vi(l),  termcap(5),  environ(5) 

BUGS 

The  undo  command  causes  all  marks  to  be  lost  on  lines  changed  and  then  restored  if  the  marked 
lines  were  changed. 

Undo  never  clears  the  buffer  modified  condition. 

The  z  command  prints  a  number  of  logical  rather  than  physical  lines.  More  than  a  screen  full  of 
output  may  result  if  long  lines  are  present. 

File  input/output  errors  don’t  print  a  name  if  the  command  line  *  option  is  used. 

There  is  no  easy  way  to  do  a  single  scan  ignoring  case. 

The  editor  does  not  warn  if  text  is  placed  in  named  buffers  and  not  used  before  exiting  the  edi¬ 
tor. 

Null  characters  are  discarded  in  input  files,  and  cannot  appear  in  resultant  files. 

The  editor  checks  the  first  five  lines  of  the  text  file  for  commands  of  the  form  **ex: command**  or 
'*vi:command,*'  This  feature  can  result  in  unexpected  behavior,  and  is  not  recommended  in  any 
case. 

RESTRICTIONS 

The  encryption  facilities  of  ex  are  not  available  on  software  shipped  outside  the  U.S. 
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NAME 

expand,  unexpand  expand  tabs  to  spaces^  and  vice  versa 
SYNOPSIS 

expand  (  — tabstop  ]  [  — tabl,tab2 . tabn  ]  (  file  ] 

unexpand  [  — a  ]  [  file  •  •  •  | 

DESCRIPTION 

Expand  copies  the  named  files  (or  the  standard  input)  to  the  standard  output,  with  tabs  changed 
into  spaces  (blanks).  Backspace  characters  are  preserved  into  the  output  and  decrement  the 
column  count  for  tab  calculations.  Expand  is  useful  for  pre-processing  character  files  (before 
sorting,  looking  at  specific  columns,  etc.)  that  contain  tabs. 

Unexpand  copies  the  named  files  (or  the  standard  input)  to  the  standard  output,  putting  tabs 
back  into  the  data.  By  default  only  leading  spaces  (blanks)  and  tabs  are  converted  to  strings  of 
tabs,  but  this  can  be  overridden  by  the  —a  option  (sec  the  optione  section  below). 

EXPAND  OPTIONS 
—tabstop 

Specified  as  a  single  argument  sets  tabs  tabstop  spaces  apart  instead  of  the  default  8. 

— tabl|tab2|. .  .^tabn 

Set  tabs  at  the  columns  specified  by  tahU^m 

UNEXPAND  OPTIONS 

—a  Insert  tabs  when  replacing  a  run  of  two  or  more  spaces  would  produce  a  smaller  output 
file.  This  option  only  applies  to  unexpand. 


o 
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NAME 

expr  —  evaluate  arguments  as  an  expression 

SYNOPSIS 

expr  arg  . . . 

DESCRIPTION 

Expr  evaluates  expressions  as  specified  by  its  arguments.  Each  token  of  the  expression  is  a 
separate  argument.  After  evaluation,  the  result  is  written  on  the  standard  output. 

The  operators  and  keywords  are  listed  below.  The  list  is  in  order  of  increasing  precedence,  with 
equal  precedence  operators  grouped. 

expr  j  expr 

yields  the  first  expr  if  it  is  neither  null  nor  '0\  otherwise  yields  the  second  expr, 
expr  &  expr 

yields  the  first  expr  if  neither  expr  is  null  or  ‘O’,  otherwise  yields  *0’. 
expr  relop  expr 

yields  T’  if  the  indicated  comparison  is  true,  ‘0’  if  false.  The  comparison  is  numeric  if 
both  expr  are  integers,  otherwise  the  comparison  is  lexicographic,  relop  is  one  of  <  (less 
than),  <=  (less  than  or  equal  to),  =  (equal  to),  !=  (not  equal  to),  >=  (greater  than  or 
equal  to),  and  >  (greater  than). 

expr  +  expr 
expr  —  expr 

addition  or  subtraction  of  the  arguments. 

expr  *  expr 
expr  /  expr 
expr  %  expr 

multiplication,  division,  or  remainder  of  the  arguments. 
expr  :  expr 

match  string  regular-expression 

The  two  forms  of  the  matching  operator  above  are  synonymous.  The  matching  operator 
compares  the  string  first  argument  with  the  regular  expression  second  argument;  regular 
expression  syntax  is  the  same  as  that  of  ed(l).  The  \(-**\)  pattern  symbols  can  be  used 
to  select  a  portion  of  the  first  argument.  Otherwise,  the  matching  operator  yields  the 
number  of  characters  matched  (‘0’  on  failure). 

substr  string  integer-1  integer-^ 

extracts  the  subtring  of  starting  at  position  integer-!  and  of  length  integer-2  char¬ 

acters,  If  integer-!  has  a  value  greater  than  string,  expr  returns  a  null  string.  If  you  try 
to  extract  more  characters  than  there  are  in  expr  returns  all  the  remaining  char¬ 
acters  from  Beware  of  using  negative  values  for  either  integer-!  or  integer-2  as 

expr  tends  to  run  forever  in  these  cases. 

index  string  character-list 

reports  the  first  position  in  string  at  which  any  one  of  the  characters  in  character-list 
matches  a  character  in  string, 

length  string 

returns  the  length  (that  is,  the  number  of  characters)  of  string, 

(  expr  ) 

parentheses  for  grouping. 

EXAMPLES 
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To  add  1  to  the  Shell  variable  a: 
a— 'expr  $a  +  1' 

To  find  the  filename  part  (least  significant  part)  of  the  pathname  stored  in  variable  a,  which  may 
or  may  not  contain  */’: 

expr  $a  :  ^♦/\(.♦\)' 

Note  the  quoted  Shell  metacharacters* 

SEE  ALSO 

sh(l),  test(l) 

DIAGNOSTICS 

Expr  returns  the  following  exit  codes: 

0  if  the  expression  is  neither  null  nor  *0\ 

1  if  the  expression  is  null  or  ‘O’, 

2  for  invalid  expressions. 

BUGS 

Note  that  the  match,  substr,  length,  and  index  operators  cannot  themselves  be  used  as  ordi¬ 
nary  strings.  That  is,  the  expression: 

tutorial%  expr  Index  expurgatorious  length 

syntax  error 

tutorial% 

generates  the  ‘syntax  error’  message  as  shown  instead  of  the  value  1  as  you  might  expect. 
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NAME 

eyacc  —  modified  yacc  allowing  much  improved  error  recovery 
SYNOPSIS 

eyacc  |  — v  ]  j  grammar  ] 

DESCRIPTION 

Eyacc  is  an  old  version  of  yocc(l),  which  produces  tables  used  by  the  Pascal  system  and  its  error 
recovery  routines.  Eyacc  fully  enumerates  test  actions  in  its  parser  when  an  error  token  is  in  the 
look-ahead  set.  This  prevents  the  parser  from  making  undesirable  reductions  when  an  error 
occurs  before  the  error  is  detected.  The  table  format  is  different  in  eyacc  than  it  was  in  the  old 
yacc,  as  minor  changes  had  been  made  for  efficiency  reasons. 

SEE  ALSO 

yacc(l) 

Practical  LR  Error  Recovery  by  Susan  L.  Graham,  Charles  B.  Haley  and  W.  N.  Joy;  SIGPLAN 
Conference  on  Compiler  Construction,  August  1979. 

BUGS 

Pc  and  its  error  recovery  routines  should  be  made  into  a  library  of  routines  for  the  new  yacc. 
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NAME 

f77  --  FORTRAN  77  compiler 
SYNOPSIS 

f77  [  — c  I  [  — g  1  I  — o  output  I  (  — O  j  [  — C  I  [  — Dname  |  |  —Dname\^deJ\]  [  —fsky  |  |  — F  j 
[  —12  I  [  — Irfir  ]  [  — m  ]  |  — N[qx8cn] nnn  ]  [  — onetrlp  |  I  — p  ]  |  — pg  !  [  — R  j  |  [  — S  j 
I  — u  I  I  — U  ]  [  —V  I  [  — wl55  |]  filename 

DESCRIPTION 

f77  is  the  UNIX  FORTRAN  77  compiler,  which  translates  programs  written  in  the  FORTRAN  77 
programming  language  into  executable  load  modules  or  into  relocatable  binary  programs  for  sub¬ 
sequent  loading  via  the  ld{l)  linker.  In  addition  to  the  many  flag  arguments  (options),  f77 
accepts  several  types  of  files: 

Filenames  ending  in  •/  are  taken  to  be  FORTRAN  77  source  programs;  they  are  compiled,  and 
each  object  program  is  left  in  the  file  (in  the  current  directory)  whose  name  is  that  of  the  source 
with  *0  substituted  for  •/.  Filenames  ending  in  .F  are  also  taken  to  be  FORTRAN  77  source  pro¬ 
grams,  but  they  are  preprocessed  by  the  C  preprocessor  (equivalent  to  a  cc  — E  command)  before 
they  are  compiled  by  the  f77  compiler. 

Filenames  ending  in  .r  are  taken  to  be  Ratfor  source  programs;  these  are  first  transformed  by  the 
ratfor{l)  preprocessor,  then  compiled  by /77. 

In  the  same  way,  filenames  ending  in  .c  or  are  taken  to  be  C  or  assembly  source  programs  and 
are  compiled  or  assembled,  producing  ,0  files. 

OPTIONS 

The  following  options  have  the  same  meaning  as  for  cc(i).  See  /rf(l)  for  load-time  options. 

— c  Suppress  loading  and  produce  a  .o  file  for  each  source  file. 

— g  Produce  additional  symbol  table  information  for  d^j(l).  Also  pass  the  — Ig  flag  to  W(l). 

— o  output 

Name  the  final  output  file  output  instead  of  Umout. 

The  following  options  are  peculiar  to  /77: 

— O  Optimize  the  object  code.  This  invokes  both  the  global  intermediate  code  optimizer  and 

the  object  code  optimizer. 

— C  Compile  code  to  check  that  subscripts  are  within  the  declared  array  bounds. 

— Dname 

—Dname=  definition 

Define  the  name  to  the  C  preprocessor,  as  if  by  *#define\  If  no  definition  is  given,  the 
name  is  defined  as  "1**.  (  .F  suffix  files  only). 

— fsky  Generate  code  which  assumes  the  presence  of  a  SKY  floating-point  processor  board.  Pro¬ 
grams  compiled  with  this  option  can  only  be  run  in  systems  that  have  a  SKY  board 
installed.  Programs  compiled  without  the  —fsky  option  will  use  the  SKY  board  if  it  is 
present,  but  won’t  run  as  fast  as  they  would  if  the  —fsky  option  were  used.  If  any  part 
of  a  program  is  compiled  using  the  —fsky  option,  you  must  also  use  this  option  when 
linking  with  the  /77  command,  since  a  different  set  of  startup  routines  is  required. 

— F  Apply  the  C  preprocessor  to  .F  files  and  the  Ratfor  preprocessor  to  do  not  compile  them. 

No  loading  is  done.  However,  any  .c  or  files  are  compiled  or  assembled.  ./,  but  do  not 
compile. 

—12  Make  the  default  size  of  integer  and  logical  constants  and  variables  two  bytes  rather 
than  four  bytes. 

—Idir  ‘#include’  files  whose  names  do  not  begin  with  7’  always  sought  by  the  C 
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preprocessor  first  in  the  directory  of  the  file  argument,  then  in  directories  named  in  —I 
options,  then  in  the  /u$r/ include/ f 77  directory  (applies  to  processing  of  .F  suffix  files 
only). 

— m  Apply  the  M4  preprocessor  to  each  .r  file  before  transforming  it  with  the  Ratfor  prepro¬ 
cessor. 

— N[qx8cn|nnn 

Make  static  tables  in  the  compiler  bigger.  f77  complains  if  tables  overflow  and  suggests 
you  apply  one  or  more  of  these  flags.  These  flags  have  the  following  meanings: 
q  Maximum  number  of  equivalenced  variables.  Default  is  150. 

X  Maximum  number  of  external  names  (common  block,  subroutine,  and  function 
names).  Default  is  200. 

B  Maximum  number  of  statement  numbers.  Default  is  401. 

c  Maximum  depth  of  nesting  for  control  statements  (for  example,  DO  loops). 

Default  is  20. 

n  Maximum  number  of  identifiers.  Default  is  1009. 

One  may  use  multiple  N  options  to  increase  the  size  of  multiple  tables. 

—onetrip 

Compile  DO  loops  so  that  they  are  performed  at  least  once  if  reached.  FORTRAN  77  DO 
loops  are  not  performed  at  all  if  the  upper  limit  is  smaller  than  the  lower  limit. 

— p  Produce  code  to  count  the  number  of  times  each  routine  is  called  and  estimate  the  frac¬ 
tion  of  time  spent  in  each  routine.  The  results  of  this  profiling  appear  in  a  file  called 
mon*out  when  the  program  being  profiled  terminates  normally.  An  execution  profile  of 
the  program  can  then  be  produced  using  the  prof{i)  utility. 

— pg  Produce  counting  code  in  the  manner  of  — p,  but  invoke  a  run-time  recording  mechanism 

that  keeps  more  extensive  statistics  and  produces  a  gmonmout  file  at  normal  termination. 
An  execution  profile  can  then  be  generated  by  use  of  gprof[l), 

—Rx  Use  the  string  x  as  a  Ratfor  option  in  processing  .r  files. 

— S  Compile  the  named  programs,  and  leave  the  assembly  language  output  on  corresponding 

files  suffixed  (no  file  is  created). 

— u  Make  the  default  type  of  a  variable  ‘undefined’  rather  than  using  the  FORTRAN  default 

rules. 

— U  Do  not  convert  upper  case  letters  to  lower  case.  The  default  is  to  convert  upper  case 

letters  to  lower  case,  except  within  character  string  constants. 

—V  Print  the  version  number  of  the  compiler,  and  the  name  of  each  pass  as  it  executes. 

— w|56| 

Suppress  all  warning  messages,  or  if  the  option  is  —wM,  su press  only  FORTRAN  66  com¬ 
patibility  warnings. 

Other  arguments  are  taken  to  be  either  loader  option  arguments,  or  /77- compatible  object  pro¬ 
grams,  typically  produced  by  an  earlier  run,  or  libraries  of  /77-compatible  routines.  These  pro¬ 
grams,  together  with  the  results  of  any  compilations  specified,  are  loaded  (in  the  order  given)  to 
produce  an  executable  program  in  the  file  specified  by  the  option,  or  in  a  file  named  a^out  if 
the  — o  option  is  not  specified. 

FILES 

file.|fFrsc|  input  file 

file.o  object  file 

a.out  linked  output 

./fort[pidj.?  temporary 

/usr/include/f77  directory  searched  by  the  FORTRAN  77  include  statement 
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/usr/lib/f77passX 

/lib/fl 

/lib/c2 

/lib/cpp 

/lib/bin/ratfor 

/usr/lib/libf77,a 

/lib/libc,a 

mon.out 

gmon.out 


parser 

code  generator 

optional  optimizer 

C  preprocessor 

Rat  for  preprocessor 

Fortran  library 

C  library,  see  Section  3 

file  produced  for  analysis  by  prof(l) 

file  produced  for  analysis  by  gprof(l) 


SEE  ALSO 

FORTRAN  Programmer's  Guide  for  the  Sun  Workstation 
prof(l),  gprof(l),  cc(l),  !d(l),  ratfor(l) 


DIAGNOSTICS 

The  diagnostics  produced  by  f77  itself  are  intended  to  be  self-explanatory.  Occasional  messages 
may  be  produced  by  the  loader. 
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NAME 

false,  true  —  provide  truth  values 

SYNOPSIS 

true 

false 

DESCRIPTION 

True  and  false  are  usually  used  in  a  Bourne  shell  script.  They  test  for  the  appropriate  status 
"true"  or  "false"  before  running  (or  failing  to  run)  a  list  of  commands. 

EXAMPLE 

while  false 
do 

command  list 
done 

SEE  ALSO 

csh(l),  sh(l),  true(l) 

DIAGNOSTICS 

False  has  exit  status  nonzero. 
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NAME 

file  —  determine  file  type 

SYNOPSIS 

file  I  --f  I  file  ... 

DESCRIPTION 

File  performs  a  series  of  tests  on  each  file  in  an  attempt  to  determine  what  its  contents  are.  If 
an  argument  appears  to  be  ASCII,  file  examines  the  first  512  bytes  and  tries  to  guess  its 
language. 

OPTIONS 

— f  If  the  — f  flag  is  used,  file  assumes  that  the  filename  given  next  on  the  command  line  is  a 

file  containing  a  list  of  files,  and  operates  on  each  file  listed. 

EXAMPLE 

The  example  illustrates  the  use  of  file  on  all  the  files  in  a  specific  user’s  directory: 


%  pwd 

/usr/henry/misc 

%I8 

bensusan 

fortran. mss  messages 

romero 

toolkit.tr 

command, list 

jokes  pascal. mss 

squash 

useful. news 

counts 

letters  play.mss 

tech. papers 

vT.stuff 

deuter 

memos  road  map. mss 

titles 

window 

%flle  ♦ 

bensusan: 

roff,  nrofi,  or  eqn  input  text 

command.Iist: 

roff,  nroff,  or  eqn  input  text 

counts: 

ascii  text 

deuter: 

roff,  nroff,  or  eqn  input  text 

fortran. mss: 

roff,  nroff,  or  eqn  input  text 

jokes: 

directory 

letters: 

directory 

memos: 

directory 

messages: 

directory 

pascal. mss: 

roff,  nroff,  or  eqn  input  text 

play. mss: 

roff,  nroff,  or  eqn  input  text 

roadmap. mss: 

roff,  nroff,  or  eqn  input  text 

romero: 

roff,  nroff,  or  eqn  input  text 

squash: 

directory 

tech. papers: 

directory 

titles: 

ascii  text 

toolkit.tr: 

roff,  nroff,  or  eqn  input  text 

useful. news: 

directory 

vT.stuff: 

archive 

window: 

directory 

% 


BUGS 

file  often  makes  mistakes.  In  particular,  it  often  suggests  that  command  files  are  C  programs. 
Does  not  recognize  Pascal  or  LISP. 
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NAME 

find  —  find  files 
SYNOPSIS 

find  pathname-list  expression 
DESCRIPTION 

Find  recursively  descends  the  directory  hierarchy  for  each  pathname  in  the  pathname- list  (that 
is,  one  or  more  pathnames)  seeking  files  that  match  a  boolean  expression  written  in  the  primaries 
given  below.  In  the  descriptions,  the  argument  n  is  used  as  a  decimal  integer  where  means 
more  than  n,  — n  means  less  than  n,  and  n  means  exactly  n. 

—name  filename 

True  if  the  filename  argument  matches  the  current  file  name.  Norma!  Shell  argu¬ 
ment  syntax  may  be  used  if  escaped  (watch  out  for  *?’  and  *♦’). 

—perm  onum 

True  if  the  file  permission  flags  exactly  match  the  octal  number  onum  (see  cftmod(l)). 
If  onum  is  prefixed  by  a  minus  sign,  more  flag  bits  (017777,  see  stat{2))  become 
significant  and  the  flags  are  compared:  (flags&onum)=^onum, 

—type  c  True  if  the  type  of  the  file  is  c,  where  c  is  b,  c,  d,  f  or  1  for  block  special  file,  charac¬ 
ter  special  file,  directory,  plain  file,  or  symbolic  link, 

—links  n  True  if  the  file  has  n  links. 

—user  uname 

True  if  the  file  belongs  to  the  user  uname  (login  name  or  numeric  user  ID). 

—group  gname 

True  if  the  file  belongs  to  group  gname  (group  name  or  numeric  group  ID). 

— sisc  n  True  if  the  file  is  n  blocks  long  (512  bytes  per  block). 

— Inum  n  True  if  the  file  has  inode  number  n, 

— atlme  n  True  if  the  file  has  been  accessed  in  n  days. 

— mtlme  n 

True  if  the  file  has  been  modified  in  n  days. 

—exec  command 

True  if  the  executed  command  returns  a  zero  value  as  exit  status.  The  end  of  the 
command  must  be  punctuated  by  an  escaped  semicolon.  A  command  argument  *{}’  is 
replaced  by  the  current  pathname. 

—ok  command 

Like  —exec  except  that  the  generated  command  is  written  on  the  standard  output, 
then  the  standard  input  is  read  and  the  command  executed  only  upon  response  y. 

—print  Always  true;  the  current  pathname  is  printed. 

-newer  file 

True  if  the  current  file  has  been  modified  more  recently  than  the  argument  file. 

The  primaries  may  be  combined  using  the  following  operators  (in  order  of  decreasing  precedence): 

1)  A  parenthesized  group  of  primaries  and  operators  (parentheses  are  special  to  the  Shell  and 
must  be  escaped). 

2)  The  negation  of  a  primary  (1’  is  the  unary  not  operator). 

3)  Concatenation  of  primaries  (the  and  operation  is  implied  by  the  juxtaposition  of  two  pri¬ 
maries). 

4)  Alternation  of  primaries  (‘—o’  is  the  or  operator). 
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EXAMPLE 

In  our  local  development  system,  we  keep  a  file  called  TIMESTAMP  all  the  manual  page  direc¬ 
tories.  Here  is  how  to  find  all  entries  that  have  been  updated  since  TIMESTAMP  yizs  created: 
angel%  find  /u8r/xnan/inan2  —newer  /usr/man/manZ/TIMB STAMP  —print 
/usr/man/man2 
/usr/man/man2/socket.2 
/usr/man/man2/mmap.2 
angel% 


To  find  all  the  files  called  starting  from  the  current  user’s  directory: 

angel%  find  •  —name  Intro.mBs  —print 
./manuals/assembler/intro.mss 
./ manuals/sun.core /intro.mss 
./manuals/driver.tut/intro.mss 
./manuals/users.guide/intro.mss 
./manuals/refman/intro.mss 
./manuals/sys. manager /intro.mss 
./manuals/sys.manager/uucp.impl/intro.mss 
./supplements/general.works/unix.introduction/intro.mss 
./supplements/programming.tools/sccs/intro.mss 
angel% 

To  remove  all  files  named  ‘a.out’  or  ‘*.0’  that  have  not  been  accessed  for  a  week: 

angel%  find  /  \(  —name  a.out  — o  —name  V.o’  \)  — atime  +7  —exec  rm  *{}*  \; 

angel% 

Note  that  the  {  }  characters  must  be  quoted  when  using  the  C  shell. 

FILES 

/etc/passwd 

/etc/group 

SEE  ALSO 

sh(l),  test(l),  fs(5) 

BUGS 

The  syntax  is  painful. 
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NAME 

ftnt  —  simple  text  formatter 
SYNOPSIS 

fmt  [  -width  ]  [  -c  j  I  filename  ...  \ 

DESCRIPTION 

Fmt  is  a  simple  text  formatter  which  reads  the  concatenation  of  input  files  (or  standard  input  if 
none  are  given)  and  produces  on  standard  output  a  version  of  its  input  with  lines  as  long  as  possi¬ 
ble  without  execeeding  width  characters.  Width  defaults  to  72.  Blank  lines  and  interword  spac¬ 
ing  is  preserved  in  the  output. 

OPTIONS 

—width  Fill  output  lines  to  within  toidtk  columns. 

— c  Crown  margin  mode  -  the  first  two  lines  following  an  empty  line  retain  their  indention. 

Subsequent  non-blank  lines  are  aligned  with  the  second. 

In  normal  mode,  the  spacing  at  the  beginning  of  the  input  lines  is  preserved  in  the  output.  Lines 
retain  their  separation  if  the  input  indenting  increases,  but  may  be  concatenated  otherwise. 

Fmt  is  meant  to  format  mail  messages  prior  to  sending,  but  may  also  be  useful  for  other  simple 
tasks.  For  instance,  in  the  vi  text  editor,  the  command; 

!}fmt 

reformats  a  paragraph,  making  the  lines  reasonably  even  length. 

SEE  ALSO 

nrofl(l),  mail(l) 

BUGS 

Fmt  was  designed  to  be  simple  and  fast  -  for  more  complex  operations,  the  standard  text  proces¬ 
sors  are  likely  to  be  more  appropriate. 


136 


Last  change;  1  February  1985 


Sun  Release  2.0 


FOLD(l) 


USER  COMMANDS 


FOLD(l) 


NAME 

fold  —  fold  long  lines  for  finite  width  output  device 
SYNOPSIS 

fold  [  -mdtk  ]  I  file  ...  I 
DESCRIPTION 

Fold  is  a  filter  which  folds  the  contents  of  the  specified  files,  or  the  standard  input  if  no  files  arc 
specified,  breaking  the  lines  to  have  maximum  width  width.  The  default  for  width  is  80, 
should  be  a  multiple  of  8  if  tabs  are  present,  or  the  tabs  should  be  expanded  using  expand(l) 
before  using  fold. 

SEE  ALSO 

expand(l) 

BUGS 

Folding  may  not  work  correctly  if  underlining  is  present. 
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NAME 

fonttool  —  a  vfont  screen-font  editor 
SYNOPSIS 

fonttool  I  — W|generic_tooLarg  ]  j  [  font^name  | 

DESCRIPTION 

fonttool  is  an  editor  for  fixed- width  fonts  in  vfont{S)  format  whose  characters  are  no  taller  than 
24  pixels  {larger  characters  will  not  fit  completely  onto  the  screen). 

OPTIONS 

—'Wgeneric^tool^arg 

fonttool  accepts  any  generic  tool  argument  as  described  in  mntoolsfl).  Otherwise,  you 
can  manipulate  the  tool  via  the  Tool  Manger  Menu. 

COMMANDS 

To  edit  a  font,  type  ‘fonttool’.  A  font_name  may  be  supplied  on  the  command  line  or  may  be 
typed  into  the  option  subwindow  once  the  program  has  started.  If  it  exists,  the  font_name  file 
must  be  in  u/on<(5)  format.  When  the  program  starts,  it  displays  a  single  large  window  contain¬ 
ing  four  subwindows.  From  top  to  bottom,  the  four  subwindows  are: 

1)  The  top  subwindow,  a  message  subwindow,  displays  messages,  prompts,  and  warnings. 

2)  The  second  subwindow  from  the  top,  an  option  subwindow,  allows  you  to  set  global  parame¬ 
ters  for  the  entire  font  and  specify  operations  for  editing  any  single  character.  The  options 
are: 

(Read)  Read  in  the  font  specified  in  the  file  name  field.  The  program  will  warn  you  if 
you  try  to  read  over  a  modified  font. 

(Save)  Write  the  current  font  onto  disk  with  the  name  in  file  nsime  field. 

(Exit)  Quit  the  program;  warns  you  if  you  have  modified  the  font. 

Font  name: 

The  name  of  the  font. 

Max  Width  and  Max  Height: 

The  size,  in  pixels,  of  the  largest  character  in  the  font.  If  you  edit  an  existing 
font,  these  parameters  are  set  automatically;  you  must  set  them  if  you  are  creat¬ 
ing  a  new  font.  Changing  either  of  these  values  for  an  existing  font  may  alter  the 
glyph  of  some  characters  of  the  font.  If  the  glyph  size  of  a  character  is  larger 
than  the  new  max  size,  then  that  character  is  clipped  to  the  new  size  (its  bottom 
and  right  edges  are  moved  in).  However,  if  a  glyph’s  size  is  smaller  than  the  new 
size,  the  glyph  is  left  alone. 

Caps  Height: 

The  top  of  a  capital  letter  in  the  font  is  this  many  pixels  above  the  baseline. 

X-He!ght: 

The  top  of  a  lower  case  letter  (that  is,  a  lower  case  “x”)  is  this  many  pixels  above 
the  baseline. 

Note:  When  an  existing  font  is  edited,  the  values  of  Caps  Height  and  X-Helght  are 

estimated  by  fonttool,  and  may  require  some  adjustment. 

Baseline:  The  number  of  pixels  from  the  top  (».e.,  the  upper  left  corner)  of  the  character  to 
the  baseline.  For  an  existing  font,  the  value  of  the  largest  baseline  distance  is 
used.  For  a  new  font,  each  character  will  have  the  same  baseline  distance.  If  this 
value  is  changed,  then  the  baseline  distance  for  all  characters  in  the  font  will  be 
the  new  value. 

(Apply)  Apply  the  current  values  of  Max  width.  Max  Height,  Capa  Height,  X- 
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Height,  and  Baseline  to  the  font.  That  is,  changes  made  to  these  values  do  not 
take  effect  until  Apply  is  selected. 

Operation: 

This  is  a  list  of  drawing  and  editing  operations  that  you  can  perform  on  a  charac¬ 
ter.  For  drawing,  the  left  mouse  button  draws  in  black,  and  the  middle  draws  in 
white.  Operations  are: 

Single  Pt  Press  a  mouse  button  down  and  a  grey  cell  will  appear;  move  the 
mouse  and  the  cell  will  follow  it.  Releasing  the  the  button  will  draw. 

Pt  Wipe  Pressing  a  button  down  will  draw  and  moving  with  the  button  down 
will  continue  drawing  until  the  button  is  released. 

Button  down  marks  the  end  point  of  a  line;  moving  with  the  button 
down  rubber  bands  a  line;  releasing  button  draws  the  line. 

Like  Line  except  draws  a  rectangle. 

Button  down  marks  one  end  of  rectangle,  and  moving  rubber  bands 
the  outline  of  the  rectangle.  Button  up  places  the  contents  of  the  rec¬ 
tangle  into  a  buffer  and  then  “cuts”  (draws  in  white)  the  rectangular 
region  from  the  character.  The  Paste  operation  (below)  gets  the  data 
from  the  buffer. 

Like  Cut  except  that  the  region  is  just  copied;  no  change  is  made  to 
the  character. 

Button  down  displays  a  rectangle  the  size  o^the  region  in  the  buffer. 
Moving  with  the  button  down  moves  the  rectangle.  Button  up  pastes 
the  contents  of  the  buffer  into  the  character. 

The  contents  of  the  paste  buffer  cannot  be  transferred  between  tools. 

In  Copy  or  Cut  mode,  holding  down  the  shift  key  while  pressing  the 
left  or  middle  mouse  button  will  preform  a  "Paste"  action.  For  best 
results,  after  placing  a  region  in  the  buffer,  press  down  the  shift  key 
and  hold  it  down,  then  press  down  the  mouse  button.  Release  the 
mouse  key  to  paste  the  region  and  then  release  the  shift  key. 

3)  The  third  subwindow  echoes  the  characters  in  the  current  font  as  they  are  typed.  Note  that 
the  cursor  must  be  in  this  window  in  order  to  see  the  characters.  Your  character  delete  key 
will  delete  the  echoed  characters. 

4)  The  bottom  subwindow,  the  editing  subwindow,  displays  eight  smaller  squares  at  its  top; 
these  are  called  edit  buttons.  The  top  section  of  each  of  these  buttons  contains  a  line  of 
text  in  the  form  nnn:  c,  where  nnn  is  the  hexidecimal  number  of  the  character  and  c  is  the 
standard  ASCII  character  corresponding  to  that  number.  In  the  lower  section  of  the  button 
the  character  of  the  current  font,  if  it  exists,  is  displayed.  Clicking  once  over  an  editing  but¬ 
ton  selects  its  character  for  editing. 

Just  below  this  row  of  buttons  is  a  box  with  the  characters  “0  9  A  Z  a  z”  in  it.  This  box  is 
called  a  slider  The  slider  allows  you  to  scroll  around  in  the  font  and  select  which  section  of 
the  font  you  want  displayed  in  the  edit  buttons.  The  black  rectangle  near  “a”  is  an  indica¬ 
tor  which  shows  the  section  of  the  font  that  is  displayed  in  the  buttons  above.  To  move  the 
indicator,  select  it  by  pressing  the  left  or  middle  mouse  button  down  over  the  indicator  and 
then  move  the  mouse  to  the  left  or  right  with  the  button  down;  the  indicator  will  slide  along 
with  the  cursor.  Releasing  the  button  selects  the  new  section  of  the  font.  A  faster  method  of 
moving  about  in  the  font  is  to  just  press  down  and  release  the  mouse  button  above  the  area 
you  want  without  bothering  to  drag  the  indicator.  Another  method  of  scrolling  through  the 
characters  of  the  font  is  to  press  a  key  on  the  keyboard  when  the  cursor  is  in  the  bottom 
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window;  that  character  is  the  first  one  displayed  in  the  edit  buttons. 

EDITING  CHARACTERS; 

To  edit  a  character,  click  once  over  the  edit  button  where  the  character  is  displayed.  When  you 
do  this,  an  edit  pad  will  appear  in  the  bottom  subwindow. 

The  edit  pad  consists  of  an  editing  area  bordered  by  scales,  a  proof  area,  and  3  command  but¬ 
tons.  The  editing  area  is  Max.  Width  by  the  Max.  Height  when  the  pad  opens,  and  displays  a 
magnified  view  of  the  selected  character.  Black  squares  indicate  foreground  pixels.  The  editing 
area  is  surrounded  by  scales  which  show  the  current  Cap*  Height,  X>Helght  and  Baseline  in 
reverse  video. 

Just  outside  the  scales,  on  the  top,  right  side,  and  bottom  of  the  pad,  are  three  small  boxes  with 
the  capital  letters  "R",  "B",  and  "A"  in  them.  These  boxes  are  movable  sliders  that  change  the 
right  edge,  bottom  edge,  and  x-axis  advance  of  the  character  respectively.  In  a  fixed-width  font, 
these  values  are  usually  the  same  for  all  characters;  however,  in  a  variable-width  font  these  con¬ 
trols  can  be  used  to  set  these  properties  for  each  character. 

To  the  right  of  the  pad  is  the  proof  area  where  the  character  is  displayed  at  normal  (that  is, 
screen)  resolution  and  three  buttons.  The  three  buttons  are: 

Undo  Clicking  the  left  or  middle  mouse  button  undoes  the  last  operation. 

Save  Stores  the  current  representation  of  the  character  in  the  font. 

Quit  Closes  the  edit  pad. 

In  the  bottom  subwindow,  the  right  mouse  button  displays  a  menu  of  operations.  These  opera¬ 
tions  are  the  same  as  those  in  the  option  subwindow  discussed  above;  you  can  select  the  current 
operation  by  either  picking  the  operation  in  the  option  subwindow  or  by  selecting  the  appropriate 
menu  with  the  left  button  of  the  mouse.  When  the  cursor  is  in  the  other  subwindows,  the  left 
button  displays  the  standard  tool  menu. 

FILES 

fusr/lihl fonts/ fixedwidtkfonta  -  Sun-supplied  screen  fonts 
SEE  ALSO 

8Mn<oo/s(l),  vfont{5),  VBwap(l) 

BUGS 

Results  are  unpredictable  with  variable-width  fonts.  The  baseline  should  be  greater  than  0  or 
else  the  font  cannot  be  read  in  by  fonltool  or  by  sun<oo/s(I). 
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NAME 

fpr  —  print  Fortran  file 

SYNOPSIS 

fpr 

DESCRIPTION 

Fpr  is  a  filter  that  transforms  files  formatted  according  to  Fortran’s  carriage  control  conventions 
into  files  formatted  according  to  UNIX  line  printer  conventions. 

Fpr  copies  its  input  onto  its  output,  replacing  the  carriage  control  characters  with  characters 
that  will  produce  the  intended  effects  when  printed  using  /pr(l).  The  first  character  of  each  line 
determines  the  vertical  spacing  as  follows: 

(blank)  one  line 

0  two  lines 

1  to  first  line  of  next  page 

+  no  advance 

A  blank  line  (that  is,  an  empty  line)  is  treated  as  if  its  first  character  is  a  blank.  A  blank  that 
appears  as  a  carriage  control  character  is  deleted.  A  zero  is  changed  to  a  newline.  A  one  is 
changed  to  a  form  feed.  The  effects  of  a  are  simulated  using  backspaces. 

Note  that  fpr  is  known  as  asa  in  UNIX  System  V. 

EXAMPLES 

a.out  j  fpr  I  Ipr 

fpr  <  f77.output  [  Ipr 

BUGS 

Results  are  undefined  for  input  lines  longer  than  170  characters. 
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NAME 

from  who  is  my  mail  from? 

SYNOPSIS 

from  I  —Bsender  \  \  user  | 

DESCRIPTION 

From  prints  out  the  mail  header  lines  in  your  mailbox  file  to  show  you  who  your  mail  is  from.  If 
user  is  specified,  then  user’s  mailbox  is  examined  instead  of  your  own. 

OPTIONS 

-‘Bsender 

Only  display  headers  for  mail  sent  by  eender. 

FILES 

/  usr  /spool  /  mail /* 

SEE  ALSO 

bifT(l),  mail(l),  prman(l) 


j 
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NAME 

fsplit  —  split  a  multi-routine  Fortran  file  into  individual  files 
SYNOPSIS 

fsplit  I  — e  efile]  ...  [  file  ] 

DESCRIPTION 

Fsplit  takes  as  input  either  a  file  or  standard  input  containing  Fortran  source  code.  It  attempts 
to  split  the  input  into  separate  routine  files  of  the  form  name./,  where  name  is  the  name  of  the 
program  unit  (e.g.  function,  subroutine,  block  data  or  program).  The  name  for  unnamed  block 
data  subprograms  has  the  form  blkdtaNNN.f  •where  NNN  is  three  digits  and  a  file  of  this  name 
does  not  already  exist.  For  unnamed  main  programs  the  name  has  the  form  mainNNN.f.  If  there 
is  an  error  in  classifying  a  program  unit,  or  if  nomc./ already  exists,  the  program  unit  will  be  put 
in  a  file  of  the  form  zzzNNN.f  where  zzzNNN.f  does  not  already  exist. 

Normally  each  subprogram  unit  is  split  into  a  separate  file.  When  the  — e  option  is  used,  only  the 
specified  subprogram  units  are  split  into  separate  files.  E.g.: 

fsplit  — e  readit  — e  doit  prog.f 

will  split  readit  and  doit  into  separate  files. 

DIAGNOSTICS 

If  names  specified  via  the  -e  option  are  not  found,  a  diagnostic  is  written  to  standard  error. 

BUGS 

Fsplit  assumes  the  subprogram  name  is  on  the  first  noncomment  line  of  the  subprogram  unit. 
Nonstandard  source  formats  may  confuse  /split. 

It  is  hard  to  use  — e  for  unnamed  main  programs  and  block  data  subprograms  since  you  must 
predict  the  created  file  name. 
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NAME 

ftp  —  file  transfer  program 
SYNOPSIS 

ftp  [  -V  j  1  -d  1  [  -i  I  [  -n  I  [  host  \ 

DESCRIPTION 

Ftp  is  the  user  interface  to  the  ARPANET  standard  File  Transfer  Protocol.  Ftp  transfers  files  to 
and  from  a  remote  network  site. 

The  client  host  with  which  ftp  is  to  communicate  may  be  specified  on  the  command  line.  If  this 
is  done,  ftp  immediately  attempts  to  establish  a  connection  to  an  FTP  server  on  that  host;  other¬ 
wise,  ftp  enters  its  command  interpreter  and  awaits  instructions  from  the  user.  When  ftp  is 
awaiting  commands  from  the  user,  it  displays  the  prompt  “ftp>”. 


OPTIONS 

Options  may  be  specified  at  the  command  line,  or  to  the  command  interpreter. 


— V 


— n 


-I 

--d 

COMMANDS 

{ 


show  all  responses  from  the  remote  server,  as  well  as  report  on  data  transfer  statistics. 

do  not  attempt  ‘‘auto-login”  upon  initial  connection.  If  auto-login  is  enabled,  ftp  checks 
the  .netrc  file  in  the  user’s  home  directory  for  an  entry  describing  an  account  on  the 
remote  machine.  If  no  entry  exists,  ftp  uses  the  login  name  on  the  local  machine  as  the 
user  identity  on  the  remote  machine,  and  prompts  for  a  password  and,  optionally,  an 
account  with  which  to  login. 

turn  on  interactive  prompting  during  mutliple  file  transfers  (unimplemented), 
enable  debugging. 

Invoke  a  shell  on  the  local  machine. 


ascii  Set  the  file  transfer  type  to  network  ASCII,  This  is  the  default  type, 
bell  Arrange  that  a  bell  be  sounded  after  each  file  transfer  command  is  completed, 
binary  Set  the  file  transfer  type  to  support  binary  image  transfer, 
bye  Terminate  the  FTP  session  with  the  remote  server  and  exit  ftp. 


cd  remote-directory 

Change  the  working  directory  on  the  remote  machine  to  remote-directory. 

close  Terminate  the  FTP  session  with  the  remote  server,  and  return  to  the  command  inter¬ 
preter. 

delete  remote- file 

Delete  the  file  remote-file  on  the  remote  machine, 
debug  I  debug-value  { 

Toggle  debugging  mode.  If  an  optional  debug-value  is  specified  it  is  used  to  set  the 
debugging  level.  When  debugging  is  on,  ftp  prints  each  command  sent  to  the  remote 
machine,  preceded  by  the  string 


dir  [  remote-directory  |  |  local-file  | 

Print  a  listing  of  the  directory  contents  in  the  directory,  remote-directory,  and,  option¬ 
ally,  placing  the  output  in  local-file.  If  no  directory  is  specified,  the  current  working 
directory  on  the  remote  machine  is  used.  If  no  local  file  is  specified,  output  comes  to  the 
terminal. 


form  format 

Set  the  file  transfer  form  to  format.  The  default  format  is  “file”, 
get  remote-file  \  local-file  j 
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Retrieve  the  remote-file  and  store  it  on  the  local  machine.  If  the  local  file  name  is  not 
specified,  it  is  given  the  same  name  it  has  on  the  remote  machine.  The  current  settings 
for  type,  form,  mode,  and  structure  are  used  while  transferring  the  file. 

help  I  command  \ 

Print  an  informative  message  about  the  meaning  of  command.  If  no  argument  is  given, 
ftp  prints  a  list  of  the  known  commands. 

led  [  directory  ] 

Change  the  working  directory  on  the  local  machine.  If  no  directory  is  specified,  the 
user’s  home  directory  is  used. 

1b  [  remote-directory  ]  [  local-file  | 

Print  an  abbreviated  listing  of  the  contents  of  a  directory  on  the  remote  machine.  If 
remote-directory  is  left  unspecified,  the  current  working  directory  is  used.  If  no  local  file 
is  specified,  the  output  is  sent  to  the  terminal. 

mode  [  mode-name  | 

Set  the  file  transfer  mode  to  mode-name.  The  default  mode  is  ^‘stream”  mode. 

mkdir  directory-name 

Make  a  directory  on  the  remote  machine. 

open  host  I  port  j 

Establish  a  connection  to  the  specified  host  FTP  server.  An  optional  port  number  may 
be  supplied,  in  which  case,  ftp  will  attempt  to  contact  an  FTP  server  at  that  port.  If  the 
auto-login  option  is  on  (default),  ftp  will  also  attempt  to  automatically  log  the  user  in  to 
the  FTP  server  (see  below). 

prompt 

Toggle  interactive  prompting.  Interactive  prompting  occurs  during  multiple  file  transfers 
to  allow  the  user  to  selectively  retrieve  or  store  files.  If  prompting  is  turned  off  (default), 
any  mget  or  mput  will  transfer  all  files. 

put  local-file  [  remote-file  | 

Store  a  local  file  on  the  remote  machine.  If  remote-file  is  left  unspecified,  the  local  file 
name  is  used  in  naming  the  remote  file.  File  transfer  uses  the  current  settings  for  type, 
format,  mode,  and  structure, 

pwd  Print  the  name  of  the  current  working  directory  on  the  remote  machine, 
quit  A  synonym  for  bye. 
quoteor^i  argS  ... 

The  arguments  specified  are  sent,  verbatim,  to  the  remote  FTP  server.  A  single  FTP 
reply  code  is  expected  in  return. 

reev  remote-file  \  local-file  | 

A  synonym  for  get. 

remotehelp  |  command-name  | 

Request  help  from  the  remote  FTP  server.  If  a  command-name  is  specified  it  is  supplied 
to  the  server  as  well. 

rename  [  from]  [  to  ] 

Rename  the  file  from  on  the  remote  machine,  to  the  file  to, 

rmdir  directory-name 

Delete  a  directory  on  the  remote  machine. 

Bend  local-file  [  remote-file  j 
A  synonym  for  put. 

BtatuB  Show  the  current  status  of  ftp. 
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struct  I  struct-namt  \ 

Set  the  file  transfer  structure  to  struet-name.  By  default  “stream”  structure  is  used, 
tenex  Set  the  file  transfer  type  to  that  needed  to  talk  to  TENEX  machines, 
trace  Toggle  packet  tracing, 
type  I  type-name  | 

Set  the  file  transfer  type  to  type-name.  If  no  type  is  specified,  the  current  type  is 
printed.  The  default  type  is  network  ASCII. 

user  user-name  |  password  ]  ]  account  | 

Identify  yourself  to  the  remote  FTP  server.  If  the  password  is  not  specified  and  the 
server  requires  it,  ftp  will  prompt  the  user  for  it  (after  disabling  local  echo).  If  an 
account  field  is  not  specified,  and  the  FTP  server  requires  it,  the  user  will  be  prompted 
for  it.  Unless  ftp  is  invoked  with  “auto-login”  disabled,  this  process  is  done  automatically 
on  initial  connection  to  the  FTP  server. 

verbose 

Toggle  verbose  mode.  In  verbose  mode,  all  responses  from  the  FTP  server  are  displayed 
to  the  user.  In  addition,  if  verbose  is  on,  when  a  file  transfer  completes,  statistics  regard¬ 
ing  the  efficiency  of  the  transfer  are  reported.  By  default,  verbose  is  on. 

?  [  command  ] 

A  synonym  for  help. 

Command  arguments  which  have  imbedded  spaces  may  be  quoted  with  quote  (")  marks. 

FILE  NAMING  CONVENTIONS 

Files  specified  as  arguments  to  ftp  commands  are  processed  according  to  the  following  rules. 

1)  If  the  file  name  is  specifed,  the  stdln  (for  reading)  or  Btdout  (for  writing)  is  used. 

2)  If  the  first  character  of  the  file  name  is  “|”,  the  remainder  of  the  argument  is  interpreted 
as  a  shell  command.  Ftp  then  forks  a  shell,  using  pnpen(3S)  with  the  argument  supplied, 
and  reads  (writes)  from  the  stdout  (stdin).  If  the  shell  command  includes  spaces,  the 
argument  must  be  quoted;  e.g.  “"j  Is  -It"”.  A  particularly  useful  example  of  this  mechan¬ 
ism  is:  “dir  |more". 

3)  Failing  the  above  checks,  local  file  names  are  expanded  according  to  the  rules  used  in  the 
csA(l).  After  the  name  is  expaned,  if  more  than  one  filename  matches,  only  the  first 
filename  is  used. 

FILE  TRANSFER  PARAMETERS 

The  FTP  specification  specifies  many  parameters  which  may  affect  a  file  transfer.  The  type  may 
be  one  of  “ascii”,  “image”  (binary),  “ebcdic”,  and  “local  byte  size”  (for  PDP-lO’s  and  PDP-20’s 
mostly).  Ftp  supports  the  ascii  and  image  types  of  file  transfer. 

Ftp  supports  only  the  default  values  for  the  remaining  file  transfer  parameters:  mode,  form,  and 
struct. 

BUGS 

Many  FTP  server  implementations  do  not  support  experimental  operations  such  as  print  working 
directory.  Aborting  a  file  transfer  does  not  work  right;  if  one  attempts  this  the  local  ftp  will 
likely  have  to  be  killed  by  hand.  VAX  sites  running  the  BBN  FTP  server  appear  to  ignore  the 
PORT  command  while  indicating  complicity;  this  locks  up  all  file  transfers. 
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NAME 

gcore  —  get  core  images  of  running  processes 

SYNOPSIS 

gcore  process-id  ... 

DESCRIPTION 

Gcore  creates  a  core  image  of  each  specified  process.  Such  an  image  can  be  used  with  adhiiS  or 
dbx{l).  ^  ’ 

FILES 

core.<process-id>  core  images 

BUGS 

Paging  activity  that  occurs  while  qeote  is  running  may  cause  the  program  to  become  confused. 
For  best  results,  the  desired  processes  should  be  stopped. 
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NAME 

get  —  get  a  version  of  an  SCCS  file 
SYNOPSIS 

/usr /secs/get  [  — r  SID  ]  |  -c  cutoff  |  [  —I  list  ]  (  -x  lUt  |  [  -a  aeq-no.  |  [  — k  ]  [  -«  ]  1 

-MpI! 

1  -p  ]  1  -m  ]  I  -n  j  I  -8  I  [  ~b  )  I  -g  1  I  -t )  file  ... 

DESCRIPTION 

Get  generates  an  ASCII  text  file  from  each  named  SCCS  file  according  to  the  specified  option. 
Arguments  may  be  specified  in  any  order,  options  apply  to  all  named  SCCS  files.  If  a  directory  is 
named,  get  behaves  as  though  each  file  in  the  directory  were  specified  as  a  named  file,  except 
that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with  8.)  and  unreadable  files 
are  silently  ignored.  If  a  name  of  —  is  given,  the  standard  input  is  read;  each  line  of  the  standard 
input  is  taken  to  be  the  name  of  an  SCCS  file  to  be  processed.  Again,  non-SCCS  files  and  unread¬ 
able  files  are  silently  ignored. 

The  generated  text  is  normally  written  into  a  file  called  the  g-file  whose  name  is  derived  from 
the  SCCS  file  name  by  simply  removing  the  leading  8.;  (see  also  FILES,  below). 

OPTIONS 

Options  are  explained  below  as  though  only  one  SCCS  file  is  to  be  processed,  but  the  effects  of 
any  option  argument  applies  independently  to  each  named  file. 

—rSID  The  5CCS  /Dentification  string  (SID)  of  the  version  (delta)  of  an  SCCS  file  to  be 
retrieved.  Table  1  below  shows,  for  the  most  useful  cases,  what  version  of  an  SCCS  file  is 
retrieved  (as  well  as  the  SID  of  the  version  to  be  eventually  created  by  delta{l)  if  the  — e 
option  is  also  used),  as  a  function  of  the  SID  specified. 

— c  cutoff 

Guio# date-time,  in  the  form;  YY[MM|DD[HH[MMISS]1]]) 

No  changes  (deltas)  to  the  SCCS  file  which  were  created  after  the  specified  cutoff  date¬ 
time  are  included  in  the  generated  ASCII  text  file.  Units  omitted  from  the  date-time 
default  to  their  maximum  possible  values;  that  is,  — c7602  is  equivalent  to 
— C7S0228235050.  Any  number  of  non-numeric  characters  may  separate  the  various  2 
digit  pieces  of  the  date-time.  This  feature  allows  one  to  specify  a  cutoff  date  in  the 

form;  — c77/2/2  0:22:25.  Note  that  this  implies  that  one  may  use  the  %E%  and  %U% 
identification  keywords. 

— e  This  get  is  for  editing  or  making  a  change  (delta)  to  the  SCCS  file  via  a  subsequent  use  of 

de(ta{l).  A  /uBr/secs/get  — e  applied  to  a  particular  version  (SID)  of  the  SCCS  file 
prevents  further  /usr/sccs/get  — e  commands  on  the  same  SID  until  delta  is  run  or  the 
J  (joint  edit)  fiag  is  set  in  the  SCCS  file  (see  aimm(l)).  Concurrent  use  of 
/uar/sccs/get  — e  for  different  SIDs  is  always  allowed. 

If  the  g-file  generated  by  a  /uBr/secs/get  — e  is  accidentally  ruined  in  the  process  of 
editing  it,  it  may  be  regenerated  by  re-running  a  get  with  the  — k  option  in  place  of  the 
— e  option. 

SCCS  file  protection  specified  via  the  ceiling,  floor,  and  authorized  user  list  stored  in  the 
SCCS  file  (sec  odm»n(l))  are  enforced  when  the  -e  option  is  used. 

— b  Used  with  the  — e  option  to  indicate  that  the  new  delta  should  have  an  SID  in  a  new 

branch  as  shown  in  Table  1.  This  option  is  ignored  if  the  b  flag  is  not  present  in  the  file 
(sec  admtn(l))  or  if  the  retrieved  delta  is  not  a  leaf  delta.  (A  leaf  delta  is  one  that  has  no 
successors  on  the  SCCS  file  tree.) 

Note;  A  branch  delta  may  always  be  created  from  a  non-leaf  delta, 

—\li$t  A  list  of  deltas  to  be  Included  (forced  to  be  applied)  in  the  creation  of  the  generated  file. 
The  list  has  the  following  syntax: 
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<Iist>  ::=  <range>  I  <list>  ,  <range> 

<range>  SID  I  SID  —  SID 

SID,  the  sees  Identification  of  a  delta,  may  be  in  any  form  shown  in  the  ‘SID  Specified’ 
column  of  Table  1.  Partial  SIDs  are  interpreted  as  shown  in  the  ‘SID  Retrieved’  column 
of  Table  1. 

— x/wf  A  list  of  deltas  to  be  excluded  (forced  not  to  be  applied)  in  the  creation  of  the  generated 
file.  See  the  —1  option  for  the  list  format, 

— k  Suppress  replacement  of  identification  keywords  (see  below)  in  the  retrieved  text  by  their 

value.  The  — k  option  is  implied  by  the  —e  option, 

— I[p]  Write  a  delta  summary  into  an  l-Jile,  If  —Ip  is  used,  the  delta  summary  is  written  on 
the  standard  output  and  the  l-file  is  not  created.  See  FILES  tor  the  format  of  the  l-file. 

— p  Write  the  text  retrieved  from  the  SCCS  file  to  the  standard  output.  No  g-Jile  is  created. 

All  output  which  normally  goes  to  the  standard  output  goes  to  the  standard  error  file 
instead,  unless  the  — s  option  is  used,  in  which  case  it  disappears. 

—8  Suppress  all  output  normally  written  on  the  standard  output.  However,  fatal  error  mes¬ 
sages  (which  always  go  to  the  standard  error  file)  remain  unaffected. 

— m  Precede  each  text  line  retrieved  from  the  SCCS  file  with  the  SID  of  the  delta  that 

inserted  the  text  line  in  the  SCCS  file.  The  format  is:  SID,  followed  by  a  horizontal  tab, 
followed  by  the  text  line. 

— n  Precede  each  generated  text  line  with  the  %M%  identification  keyword  value  (see 

below).  The  format  is:  %M%  value,  followed  by  a  horizontal  tab,  followed  by  the  text 
line.  When  both  the  — m  and  — n  options  are  used,  the  format  is:  %M%  value,  followed 
by  a  horizontal  tab,  followed  by  the  — m  option  generated  format. 

“g  Do  not  actually  retrieve  text  from  the  SCCS  file.  It  is  primarily  used  to  generate  an  /- 
file,  or  to  verify  the  existence  of  a  particular  SID. 

— i  Access  the  most  recently  created  (‘top’)  delta  in  a  given  release  (for  example,  — rl),  or 

release  and  level  (for  example,  — rl.2). 

—a  seq-no. 

The  delta  sequence  number  of  the  SCCS  file  delta  (version)  to  be  retrieved  (see 
ffcc5/i/e(5)).  This  option  is  used  by  the  comh[\)  command;  it  is  not  a  generally  useful 
option,  and  users  should  not  use  it.  If  both  the  — r  and  —a  options  are  specified,  the  —a 
option  is  used.  Care  should  be  taken  when  using  the  —a  option  in  conjunction  with  the 
— e  option,  as  the  SID  of  the  delta  to  be  created  may  not  be  what  one  expects.  The  — r 
option  can  be  used  with  the  —a  and  — e  options  to  control  the  naming  of  the  SID  of  the 
delta  to  be  created. 

For  each  file  processed,  get  responds  (on  the  standard  output)  with  the  SID  being  accessed  and 
with  the  number  of  lines  retrieved  from  the  SCCS  file. 

If  the  — e  option  is  used,  the  SID  of  the  delta  to  be  made  appears  after  the  SID  accessed  and 
before  the  number  of  lines  generated.  If  there  is  more  than  one  named  file  or  if  a  directory  or 
standard  input  is  named,  each  file  name  is  printed  (preceded  by  a  new-line)  before  it  is  processed. 
If  the  — i  option  is  used  included  deltas  are  listed  following  the  notation  ‘Included’;  if  the  — x 
option  is  used,  excluded  deltas  are  listed  following  the  notation  ‘Excluded’. 
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TABLE  1.  Determination  of  SCCS  Identification  String 


SID* 

— b  Option 

Other 

sn> 

sn)  of  Delta 

Specified 

Usedt 

Conditions 

Retrieved 

to  be  Created 

nonef 

no 

R  defaults  to  mR 

mR.mL 

mR.(mL+l) 

nonet 

yes 

R  defaults  to  mR 

mR.mL 

mR.mL.(mB+l).l 

R 

no 

R  >  mR 

mR.mL 

R.l*** 

R 

no 

R  =  mR 

mR.mL 

mR.(mL+l) 

R 

yes 

R  >  mR 

mR.mL 

mR.mL.(mB+l).l 

R 

yes 

R  =  mR 

mR.mL 

mR.mL.(mB+l).l 

R 

— 

R  <  mR  and 

R  does  not  exist 

hR.mL** 

hR.mL.(mB+l).l 

R 

— 

Trunk  succ.# 
in  release  >  R 
and  R  exists 

R.mL 

R.mL.(mB+l).l 

R.L 

no 

No  trunk  succ. 

R.L 

R.(L+1) 

R.L 

yes 

No  trunk  succ. 

R.L 

R.L.(mB+l).l 

R,L 

- 

Trunk  succ. 
in  release  >  R 

R.L 

R.L.(mB+l).l 

R.L.B 

no 

No  branch  succ. 

R.L.B.mS 

R.L.B.(mS+l) 

R.L.B 

yes 

No  branch  succ. 

R.L.B.mS 

R.L.(mB+l).l 

R.L.B.S 

no 

No  branch  succ. 

R.L.B.S 

R.L.B.(S+1) 

R.L.B.S 

yes 

No  branch  succ. 

R.L.B.S 

R.L.(mB+l).l 

R.L.B.S 

— 

Branch  succ. 

R.L.B.S 

R.L.(mB+l).l 

♦  ‘R*,  'B*,  and  ‘S*  are  the  ‘release’,  ‘level’,  ‘branch’,  and  ‘sequence’  components  of  the 

SID,  respectively;  ‘m*  means  ‘maximum’.  Thus,  for  example,  ‘R.mL’  means  ‘the  max¬ 
imum  level  number  within  release  R’;  ‘R.L.(mB+l).l’  means  ‘the  first  sequence  number 
on  the  new  branch  (that  is,  maximum  branch  number  plus  one)  of  level  L  within  release 
R’.  Note  that  if  the  SID  specified  is  of  the  form  *R.L’,  ‘R.L.B’,  or  ‘R.L.B.S’,  each  of  the 
specified  components  must  exist, 

**  ‘hR’  is  the  highest  existing  release  that  is  lower  than  the  specified,  nonexistent,  release  R. 

♦♦♦  Forces  creation  of  the  first  delta  in  a  new  release. 

#  Successor. 

t  The  — b  option  is  effective  only  if  the  b  flag  (see  flrfmtrt(l))  is  present  in  the  file.  An  entry 

of  —  means  ‘irrelevant’. 

}  This  case  applies  if  the  d  (default  SID)  flag  is  not  present  in  the  file.  If  the  d  flag  is 
present  in  the  file,  the  SID  obtained  from  the  d  flag  is  interpreted  as  if  it  had  been 
specified  on  the  command  line.  Thus,  one  of  the  other  cases  in  this  table  applies. 

IDENTIFICATION  KEYWORDS 

Identifying  information  is  Inserted  into  the  text  retrieved  from  the  SCCS  file  by  replacing 

identification  keywords  with  their  value  wherever  they  occur.  The  following  keywords  may  be 

used  in  the  text  stored  in  an  SCCS  file: 
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Keyword  Value 

%M%  Module  name:  either  the  value  of  the  m  flag  in  the  file  (sec  admin{l)),  or  if  absent,  the 
name  of  the  SCCS  file  with  the  leading  s.  removed. 

%1%  SCCS  identification  (SID)  {%H%.%h%.%B%.%S%)  of  the  retrieved  text. 

%R%  Release. 

%L%  Level. 

%B%  Branch. 

%S%  Sequence. 

%D%  Current  date  (YY/MM/DD). 

%H%  Current  date  (MM/DD/YY). 

%T%  Current  time  (HH:MM:SS). 

%E%  Date  newest  applied  delta  was  created  (YY/MM/DD). 

%G%  Date  newest  applied  delta  was  created  (MM/DD/Y5f). 

Time  newest  applied  delta  was  created  (HH:MM:SS). 

%Y%  Module  type:  value  of  the  t  flag  in  the  SCCS  file  (see  odm»n(l)). 

%F%  SCCS  file  name. 

%P%  Fully  qualified  SCCS  file  name. 

%Q%  The  value  of  the  q  flag  in  the  file  (see  orfmin(l)). 

%C%  Current  line  number.  This  keyword  is  intended  for  identifying  messages  output  by  the 
program  such  as  ‘this  shouldn’t  have  happened’  type  errors.  It  is  not  intended  to  be 
used  on  every  line  to  provide  sequence  numbers. 

%Z%  The  4-character  string  @(#)  recognizable  by  wAa/(l). 

9SW%  A  shorthand  notation  for  constructing  u;Aa((l)  strings  for  UNIX  program  files.  %W%  *» 
%Z%%M%<horizontal-tab>%I% 

%A%  Another  shorthand  notation  for  constructing  w?Aaf(l)  strings  for  non-UNIX  program  files, 
%K%  -  %Z%%Y%  %M%  %1%%Z% 

FILES 

Several  auxiliary  files  may  be  created  by  get.  These  files  are  known  generically  as  the  g-file,  I- file, 
p-file,  and  z-file.  The  letter  before  the  hyphen  is  called  the  tag.  An  auxiliary  file  name  is  formed 
from  the  SCCS  file  name:  the  last  component  of  all  SCCS  file  names  must  be  of  the  form 
n.module-name,  the  auxiliary  files  are  named  by  replacing  the  leading  s  with  the  tag.  The  g-file 
is  an  exception  to  this  scheme:  the  g-file  is  named  by  removing  the  s.  prefix.  For  example, 
s.xys.e,  the  auxiliary  file  names  would  be  xyE.c,  Lxyz.c,  p.xyz.c,  and  s.xyz.c,  respectively. 

The  g-file,  which  contains  the  generated  text,  is  created  in  the  current  directory  (unless  the  — p 
option  is  used).  A  g-file  is  created  in  all  cases,  whether  or  not  any  lines  of  text  were  generated 
by  the  get.  It  is  owned  by  the  real  user.  If  the  — k  option  is  used  or  implied  its  mode  is  644;  oth¬ 
erwise  its  mode  is  444.  Only  the  real  user  need  have  write  permission  in  the  current  directory. 

The  l-file  contains  a  table  showing  which  deltas  were  applied  in  generating  the  retrieved  text. 
The  l-file  is  created  in  the  current  directory  if  the  —1  option  is  used;  its  mode  is  444  and  it  is 
owned  by  the  real  user.  Only  the  real  user  need  have  write  permission  in  the  current  directory. 

Lines  in  the  l-fite  have  the  following  format: 

a.  A  blank  character  if  the  delta  was  applied; 

♦  otherwise. 

b.  A  blank  character  if  the  delta  was  applied  or  wasn’t  applied  and  ignored; 

♦  if  the  delta  wasn’t  applied  and  wasn’t  ignored. 

c.  A  code  indicating  a  ‘special’  reason  why  the  delta  was  or  was  not  applied: 

T:  Included. 

‘X’:  Excluded. 

‘C’:  Cut  off  (by  a  — c  option). 

d.  Blank. 

e.  SCCS  identification  (SID). 


Sun  Release  2.0 


Last  change:  6  March  1984 


151 


GET(l) 


USER  COMMANDS 


GET(l) 


f.  Tab  character. 

g.  Date  and  time  (in  the  form  YY/MM/DD  HH:MM:SS)  of  creation. 

h.  Blank. 

i.  Login  name  of  person  who  created  delta. 

The  comments  and  MR  data  follow  on  subsequent  lines,  indented  one  horizontal  tab 
character.  A  blank  line  terminates  each  entry. 

The  p-file  passes  information  resulting  from  a  /usr/secs/get  — e  along  to  delta.  Its  contents 
are  also  used  to  prevent  a  subsequent  execution  of  a  /usr/sces/get  — e  for  the  same  SID  until 
delta  is  executed  or  the  joint  edit  flag,  J,  (see  ad>nin(l))  is  set  in  the  SCCS  file.  The  p-file  is 
created  in  the  directory  containing  the  SCCS  file  and  the  effective  user  must  have  write  permis¬ 
sion  in  that  directory.  Its  mode  is  644  and  it  is  owned  by  the  effective  user.  The  format  of  the 
p-file  is:  the  gotten  SID,  followed  by  a  blank,  followed  by  the  SID  that  the  new  delta  will  have 
when  it  is  made,  followed  by  a  blank,  followed  by  the  login  name  of  the  real  user,  followed  by  a 
blank,  followed  by  the  date-time  the  get  was  executed,  followed  by  a  blank  and  the  -1  option  if  it 
was  present,  followed  by  a  blank  and  the  -x  option  if  it  was  present,  followed  by  a  new-line. 
There  can  be  an  arbitrary  number  of  lines  in  the  p-file  at  any  time;  no  two  lines  can  have  the 
same  new  delta  SID. 

The  z-file  serves  as  a  lock-out  mechanism  against  simultaneous  updates.  Its  contents  are  the 
binary  (2  bytes)  process  ID  of  the  command  (that  is,  get)  that  created  it.  The  z-file  is  created  in 
the  directory  containing  the  SCCS  file  for  the  duration  of  get.  The  same  protection  restrictions 
as  those  for  the  p-file  apply  for  the  z-file.  The  z-file  is  created  mode  444. 

SEE  ALSO 

sccs(l),  admin(l),  delta(l),  help(l),  prs(l),  what(l),  sccsfi!e(5). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 

DIAGNOSTICS 

Use  Ae/p(l)  for  explanations. 

BUGS 

If  the  effective  user  has  write  permission  (either  explicitly  or  implicitly)  in  the  directory  contain¬ 
ing  the  SCCS  files,  but  the  real  user  doesn’t,  only  one  file  may  be  named  when  the  — e  option  is 
used. 
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NAME 

gprof  —  display  call  graph  profile  data 
SYNOPSIS 

gprof  (  — a  ]  [  — b  I  [  — c  ]  [  — e  name  ]  |  — E  name  [  [  — f  name  ]  (  — P  name  |  [  — •  ]  [  — a  | 

I  object-file  1  profile-file  ...  ]  | 

DESCRIPTION 

Gprof  produces  an  execution  profile  of  C,  Pascal,  or  FORTRAN  77  programs.  The  effect  of  called 
routines  is  incorporated  in  the  profile  of  each  caller.  The  profile  data  is  taken  from  the  call 
graph  profile  file  {gmon.oul  default)  which  is  created  by  programs  compiled  with  the  — pg  option 
of  cc,  pc,  and  /77.  That  option  also  links  in  versions  of  the  library  routines  which  are  compiled 
for  profiling.  The  symbol  table  in  the  named  object  file  {a.out  default)  is  read  and  correlated 
with  the  call  graph  profile  file.  If  more  than  one  profile  file  is  specified,  the  ^pro/ output  shows 
the  sum  of  the  profile  information  in  the  given  profile  files. 

First,  a  flat  profile  is  given,  similar  to  that  provided  by  profil).  This  listing  gives  the  total  execu¬ 
tion  times  and  call  counts  for  each  of  the  functions  in  the  program,  sorted  by  decreasing  time. 

Next,  these  times  are  propagated  along  the  edges  of  the  call  graph.  Cycles  are  discovered,  and 
calls  into  a  cycle  are  made  to  share  the  time  of  the  cycle.  A  second  listing  shows  the  functions 
sorted  according  to  the  time  they  represent  including  the  time  of  their  call  graph  descendants. 
Below  each  function  entry  is  shown  its  (direct)  call  graph  children,  and  how  their  times  are  pro¬ 
pagated  to  this  function.  A  similar  display  above  the  function  shows  how  this  function’s  time 
and  the  time  of  its  descendants  is  propagated  to  its  (direct)  call  graph  parents. 

Cycles  are  also  shown,  with  an  entry  for  the  cycle  as  a  whole  and  a  listing  of  the  members  of  the 
cycle  and  their  contributions  to  the  time  and  call  counts  of  the  cycle. 

Beware  of  quantization  errors.  The  granularity  of  the  sampling  is  shown,  but  remains  statistical 
at  best.  It  is  assumed  that  the  time  for  each  execution  of  a  function  can  be  expressed  by  the 
total  time  for  the  function  divided  by  the  number  of  times  the  function  is  called.  Thus  the  time 
propagated  along  the  call  graph  arcs  to  parents  of  that  function  is  directly  proportional  to  the 
number  of  times  that  arc  is  traversed. 

The  profiled  program  must  call  exit(2)  or  return  normally  for  the  profiling  information  to  be 
saved  in  the  gmon.oul  file. 

OPTIONS 

—a  suppress  printing  statically  declared  functions.  If  this  option  is  given,  all  relevant  infor¬ 
mation  about  the  static  function  (for  instance,  time  samples,  calls  to  other  functions,  calls 
from  other  functions)  belongs  to  the  function  loaded  just  before  the  static  function  in  the 
a.out  file. 

— b  display  a  description  of  each  field  in  the  profile. 

— c  the  static  call  graph  of  the  program  is  discovered  by  a  heuristic  which  examines  the  text 

space  of  the  object  file.  Static-only  parents  or  children  are  indicated  with  call  counts  of 

0. 

— e  name 

suppress  printing  the  graph  profile  entry  for  routine  name  and  all  its  descendants  (unless 
they  have  other  ancestors  that  aren’t  suppressed).  More  than  one  — e  option  may  be 
given.  Only  one  name  may  be  given  with  each  — e  option. 

— E  name 

suppress  printing  the  graph  profile  entry  for  routine  name  (and  its  descendants)  as 
above,  and  also  excludes  the  time  spent  in  name  (and  its  descendants)  from  the  total  and 
percentage  time  computations.  More  than  one  — E  option  may  be  given.  For  example, 
— E  mcount  — E  mcleanup  is  the  default. 
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— f  name 

print  the  graph  profile  entry  only  for  routine  name  and  its  descendants.  More  than  one 
— f  option  may  be  given.  Only  one  ttomc  may  be  given  with  each  — f  option. 

— F  name 

print  the  graph  profile  entry  only  for  routine  nome  and  its  descendants  (as  — f,  above) 
and  also  uses  only  the  times  of  the  printed  routines  in  total  time  and  percentage  compu¬ 
tations.  More  than  one  — P  option  may  be  given.  Only  one  name  may  be  given  with 
each  — F  option.  The  — F  option  overrides  the  — E  option. 

—8  produce  a  profile  file  gmon.sum  which  represents  the  sum  of  the  profile  information  in  all 
the  specified  profile  files.  This  summary  profile  file  may  be  given  to  subsequent  execu¬ 
tions  of  gprof  (probably  also  with  a  — i)  option  to  accumulate  profile  data  across  several 
runs  of  an  a,out  file. 

—8  display  routines  which  have  zero  usage  (as  indicated  by  call  counts  and  accumulated 
time).  This  is  useful  in  conjunction  with  the  — c  option  for  discovering  which  routines 
were  never  called. 

FILES 

а. out 
gmon.out 
gmon.sum 

SEE  ALSO 

monitor(3),  profil(2),  cc(l),  prof(l) 

Graham,  S.L.,  Kessler,  P.B.,  McKusick,  M.K.,  ‘gprof:  A  Call  Graph  Execution  Profiler’,  Proceed¬ 
ings  of  the  SIGPLAN  '82  Symposium  on  Compiler  Construction,  SIGPLAN  Notices,  Vol.  17,  No. 

б,  pp.  120-126,  June  1982. 

BUGS 

Parents  which  are  not  themselves  profiled  will  have  the  time  of  their  profiled  children  propagated 
to  them,  but  they  will  appear  to  be  spontaneously  invoked  in  the  call  graph  listing,  and  will  not 
have  their  time  propagated  further.  Similarly,  signal  catchers,  even  though  profiled,  will  appear 
to  be  spontaneous  (although  for  more  obscure  reasons).  Any  profiled  children  of  signal  catchers 
should  have  their  times  propagated  properly,  unless  the  signal  catcher  was  invoked  during  the 
execution  of  the  profiling  routine,  in  which  case  all  is  lost. 


the  namelist  and  text  space 
dynamic  cal!  graph  and  profile 
summarized  dynamic  call  graph  and  profile 
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NAME 

gfxtool  —  Run  graphics  programs  in  the  SunWindows  environment 
SYNOPSIS 

gftciool  [  — C  ]  [  program  [  arguments  || 

OPTIONS 

— C  Redirect  system  console  output  to  this  instance  of  gfxtool. 

gfxtool  also  accepts  all  of  the  generic  tool  arguments;  see  suntool8{l)  for  a  list  of  these  arguments. 

If  a  program  argument  is  present,  gfxtool  runs  it.  If  there  are  no  arguments,  gfxtool  runs  the  pro¬ 
gram  corresponding  to  your  SHELL  environment  variable.  If  this  environment  variable  is  not 
available,  then  gfxtool  runs  /bin/sh. 

DESCRIPTION 

gfxtool  is  a  standard  tool  provided  with  SunWindows.  It  allows  you  to  run  graphics  programs 
that  don’t  overwrite  the  terminal  emulator  from  which  they  run. 

gfxtool  has  two  subwindows:  a  terminal  subwindow  and  an  empty  subwindow.  The  terminal 
subwindow  contains  a  running  shell.  Just  like  the  shelltool  (see  8helltool{l)).  Programs  invoked  in 
the  terminal  subwindow  can  run  in  the  empty  subwindow.  You  can  move  the  boundary  between 
these  two  subwindows  as  described  in  aun<oo/s(l)  under  The  Tool  Manager.  If  you  wish,  you  can 
make  gfxtool  your  console  by  entering  a  first  argument  of -C. 

Normally  you  can  use  the  mouse  and  keyboard  anywhere  in  the  empty  subwindow  to  access  Tool 
Manager  functions.  However,  some  graphics  programs  which  run  in  this  window  may  take  over 
inputs  directed  to  it.  For  example,  SunCore  uses  the  mouse  and  keyboard  for  its  own  input. 
When  you  run  such  tools,  access  the  Tool  Manager  menu  from  the  tool  boundaries  or  namestripe. 

Most  of  the  graphics  demo  programs  in  /usr/demo  will  run  in  gfxtool.  In  particular,  the  following 
demos  run  in  gfxtool: 

/  UBr/demo/bouncedemo 

Displays  a  bouncing  square.  Place  a  -n  followed  by  a  decimal  number  on  the  command 
line  to  indicate  how  many  repetitions  of  the  bounce  sequence  should  be  done. 

/usr/demo/spheresdemo 

Laboriously  computes  a  random  collection  of  shaded  spheres.  Place  a  — n  followed  by  a 
decimal  number  on  the  command  line  to  indicate  how  many  spheres  should  be  drawn. 
Colored  spheres  are  drawn  on  color  displays. 

/usr/demo/Jumpdemo 

Simulates  the  famous  Star  Wars  jump  to  light-speed  sequence  using  vector  drawing. 
Place  a  — n  followed  by  a  decimal  number  up  to  500  to  indicate  how  many  stars  should 
be  used  in  the  star  field.  Colored  stars  are  drawn  on  color  displays.  A  -e  on  the  com¬ 
mand  line  directs  the  program  to  rotate  the  color  map,  thus  producing  a  sparkling  effect. 

/usr/demo/framedemo 

Displays  a  series  of  frames,  each  of  which  contains  a  250  by  256  image  formed  of  pixels 
one  deep  (that  is,  the  image  is  a  square  monochrome  bitmap,  with  256  bits  on  a  side). 
The  frames  must  be  in  the  files  frame. 1  through  frame.n  on  the  current  working  direc¬ 
tory,  and  are  displayed  in  numerical  order.  A  set  of  sample  frames  is  available  to  you  in 
the  directory  j usrj demof gloheframesf*.  Put  a  — n  followed  by  a  decimal  number  on  the 
command  line  to  indicate  how  many  times  to  cycle  through  the  frames.  If  you  move  the 
cursor  into  the  image  window,  you  can  type  certain  characters  to  affects  the  rate  at 
which  the  frames  arc  displayed.  The  initial  rate  is  one  frame  per  second.  Typing  “S” 
causes  an  additional  one  second  delay  between  frames.  Typing  “F”  removes  one  second 
from  the  inter-frame  delay.  Typing  “s”  adds  l/20th  of  a  second.  Typing  “f”  removes 
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l/20th  of  a  second.  Typing  “Ff”  makes  the  delay  as  small  as  possible. 

For  all  these  demos  the  following  is  true:  if  no  — n  flag  appears  on  the  command  line  then  the 
program  runs  continuously  until  you  interrupt  it.  A  — r  flag  on  the  command  line  turns  the  win¬ 
dow  into  a  retained  window.  This  allows  the  image  to  reappear  when  uncovered  instead  of  res¬ 
tarting  the  demo.  You  can  also  invoke  all  these  demos  from  the  workstation  console,  i.e.,  outside 
of  the  sunioola  window  environment.  A  — d  flag  followed  by  a  display  device  name  as  in  "boun- 
cedemo  -d  /dev/cgoneO”  directs  the  demo  to  run  on  a  display  other  than  the  console. 

SEE  ALSO 

8kelltool{l) 

FILES 

"/.ttyswrc 

/usr/bin/gfxtool 

/usr/bin/suntools 

/usr/demo/* 

/  usr  /sr  c/su  n  /suntool  /  gfxtool.c 

BUGS 

If  more  than  256  characters  are  input  to  a  terminal  emulator  subwindow  without  an  intervening 
newline,  the  terminal  emulator  may  hang.  If  this  occurs,  display  the  Tool  Manager  Menu;  the 
"TTY  Hung?"  submenu  there  has  one  item,  "Flush  input",  that  you  can  invoke  to  correct  the 
problem. 
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NAME 

graph  -  draw  a  graph 
SYNOPSIS 

graph  [  —a  spacing  [  start  ]  |  |  — b  j  [  — c  string  ]  [  — g  gridstyle  |  [  —1  label  ] 

[  — m  connectmode  |  [  —•  |  [  — x  ( 1  ]  lower  [  upper  [  spacing  j  j  | 
f  — y  [  1  I  lower  [  upper  [  spacing  |  ]  ]  |  — h  fraction  |  [  — w  fraction  ]  |  — r  fraction  \ 

[  — u  fraction  j  [  — t  |  ••• 

DESCRIPTION 

Graph  with  no  options  takes  pairs  of  numbers  from  the  standard  input  as  abscissas  and  ordinates 
of  a  graph.  Successive  points  are  connected  by  straight  lines.  The  graph  is  encoded  on  the  stan¬ 
dard  output  for  display  by  the  ptot{lG)  filters. 

If  the  coordinates  of  a  point  are  followed  by  a  nonnumeric  string,  that  string  is  printed  as  a  label 
beginning  on  the  point.  Labels  may  be  surrounded  with  quotes  in  which  case  they  may  be 
empty  or  contain  blanks  and  numbers;  labels  never  contain  newlines. 

A  legend  indicating  grid  range  is  produced  with  a  grid  unless  the  — s  option  is  present. 


OPTIONS 

Each  option  is  recognized  as  a  separate  argument. 

—a  spacing  [  start  ] 

Supply  abscissas  automatically  (they  are  missing  from  the  input);  spacing  is  the  spacing 
(default  1).  start  is  the  starting  point  for  automatic  abscissas -{default  0  or  lower  limit 
given  by  — x). 

—b  Break  (disconnect)  the  graph  after  each  label  in  the  input. 

— c  string 

String  is  the  default  label  for  each  point. 

— g  gridstyle 

Gridstyle  is  the  grid  style:  0  no  grid,  1  frame  with  ticks,  2  full  grid  (default). 

—1  label  is  label  for  graph. 


—m  connectmode 

is  mode  (style)  of  connecting  lines:  0  disconnected,  1  connected  (default).  Some  devices 
give  distinguishable  line  styles  for  other  small  integers. 


— B  Save  screen,  don’t  erase  before  plotting. 


— X  ( 1  }  lower  [  upper  [  spacing  j  j 

If  1  is  present,  x  axis  is  logarithmic. 
ing^  if  present,  is  grid  spacing  on 
automatically. 

— y  [  1  ]  lower  [  upper  \  spacing  \  ] 

If  1  is  present,  y  axis  is  logarithmic. 
ing,  if  present,  is  grid  spacing  on 
automatically. 


lowerzndupper  are  lower  (and  upper)  x  limits,  spac- 
z  axis.  Normally  these  quantities  are  determined 


lower2.ndupper  are  lower  (and  upper)  y  limits,  epac- 
y  axis.  Normally  these  quantities  are  determined 


— h  fraction 

is  fraction  of  space  for  height. 

— w  fraction 

is  fraction  of  space  for  width. 

— r  fraction 

is  fraction  of  space  to  move  right  before  plotting. 
— u  fraction 
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is  fraction  of  space  to  move  up  before  plotting. 

-t  Transpose  horizontal  and  vertical  axes.  (Option  -x  now  applies  to  the  vertical  axis.) 

If  a  specified  lower  limit  exceeds  the  upper  limit,  the  axis  is  reversed. 

SEE  ALSO 

spline(lG),  plot(lG) 

BUGS 

Graph  stores  all  points  internally  and  drops  those  for  which  there  isn’t  room. 

Segments  that  run  out  of  bounds  are  dropped,  not  windowed. 

Logarithmic  axes  may  not  be  reversed. 
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NAME 

grep,  egrep,  fgrep  —  search  a  file  for  a  pattern 
SYNOPSIS 

grep  [  — V  )  [  — c  ]  [  — 1 1  [  — n  ]  [  — b  I  [  — I  ]  [  — •  ]  [  — h  ]  [  — w  j  [  — e  expression  |  expression 

[  filename  . ..  ] 

egrep  [  — v  |  [  — c  |  |  — 1  |  [  — n  ]  |  — b  [  [  — »  ]  [  — h  |  [  -^  expression  ]  [  —tfile  ]  |  expression  | 

[  filename  ]  ...  ] 

fgrep  [  -~v  j  [  -X  I  I  — c  )  I  -I  I  [  -n  ]  [  — b  J  [  -i  I  [  — ■  I  [  — h  j  [  --e  expression  j  [  -tfile  | 

[  strings  |  [  filename  )  ...  ] 

DESCRIPTION 

Commands  of  the  grep  family  search  the  input  files  (standard  input  default)  for  lines  matching  a 
pattern.  Normally,  each  line  found  is  copied  to  the  standard  output.  Grep  patterns  are  limited 
regular  expressions  in  the  style  of  ed(l).  Egrep  patterns  are  full  regular  expressions  including 
alternation.  Fgrep  searches  for  lines  that  contain  one  of  the  (newline-separated)  strings,  Fgrep 
patterns  are  fixed  strings  —  no  regular  expression  metacharacters  are  supported. 

In  general,  e^rep  is  the  fastest  of  these  programs. 

Take  care  when  using  the  characters  $♦[{()  stnd  \  in  the  expression  as  these  characters  are 
also  meaningful  to  the  Shell.  Enclose  the  entire  expression  argument  in  single  quotes  '  '  if  you 
need  any  of  the  above  special  characters  in  the  expression. 

When  any  of  the  grep  utilities  is  applied  to  more  than  one  input  file,  the  name  of  the  file  is 
displayed  preceding  each  line  which  matches  the  pattern.  The  filename  is  not  displayed  when 
processing  a  single  file,  so  if  you  actually  want  the  filename  to  appear,  use  /dev/ null  as  a  second 
file  in  the  list. 

OPTIONS 

—V  Invert  the  search  to  only  display  lines  that  do  not  match. 

—X  Display  only  those  lines  which  match  exactly  —  that  is,  only  lines  which  match  in  their 

entirety  {fgrep  only). 

— c  Display  a  count  of  matching  lines. 

—I  List  the  names  of  files  with  matching  lines  (once)  separated  by  newlines. 

— n  Precede  each  line  by  its  relative  line  number  in  the  file. 

^b  Precede  each  line  by  the  block  number  on  which  it  was  found.  This  is  sometimes  useful 
in  locating  disk  block  numbers  by  context. 

—I  Ignore  the  case  of  letters  in  making  comparisons  —  that  is,  upper  and  lower  case  are  con¬ 
sidered  identical.  This  applies  to  grep  and  fgrep  only. 

—8  Work  silently,  that  is,  display  nothing  except  error  messages.  This  is  useful  for  checking 
the  error  status. 

— h  Do  not  display  filenames. 

— w  search  for  the  expression  as  a  word  as  if  surrounded  by  ‘\<*  and  ‘\>*,  see  cz(l).  grep 

only. 

— e  expression 

Same  as  a  simple  expression  argument,  but  useful  when  the  expression  begins  with  a  — . 

— f  file  Take  the  regular  expression  (egrep)  or  string  list  (fgrep)  from  file, 

REGULAR  EXPRESSIONS 

In  the  following  description  ‘character’  excludes  newline: 

\  Is  an  escape  character:  \  followed  by  any  single  character  other  than  newline  matches 
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that  character. 

Anchored  match:  matches  the  beginning  of  a  line. 

$  Anchored  match:  matches  the  end  of  a  line, 

♦  (period)  matches  any  character. 

c  Where  c  is  any  single  character  not  otherwise  endowed  with  special  meaning  matches 
that  character. 

Character  class:  match  any  single  character  from  string.  Ranges  of  ASCII  character 
codes  may  be  abbreviated  as  in  ‘a— zO— 9’.  A  ]  may  occur  only  as  the  first  character  of 
the  string.  A  literal  —  must  be  placed  where  it  can’t  be  mistaken  as  a  range  indicator. 
A  (circumflex)  character  immediately  after  the  open  bracket  negates  the  sense  of  the 
character  class,  that  is,  the  pattern  matches  any  character  except  those  in  the  character 
class. 

♦  Closure:  a  regular  expression  followed  by  an  ♦  (asterisk)  matches  a  sequence  of  0  or  more 
matches  of  the  regular  expression. 

+  Closure:  a  regular  expression  followed  by  a  +  (plus)  matches  a  sequence  of  1  or  more 
matches  of  the  regular  expression. 

?  Closure:  a  regular  expression  followed  by  a  ?  (question  mark)  matches  a  sequence  of  0  or 

1  matches  of  the  regular  expression. 

concatenation 

Two  regular  expressions  concatenated  match  a  match  of  the  first  followed  by  a  match  of 
the  second. 

}  Alternation:  two  regular  expressions  separated  by  [  or  newline  match  either  a  match  for 

the  first  or  a  match  for  the  second  [egrep  only). 

()  A  regular  expression  enclosed  in  parentheses  matches  a  match  for  the  regular  expression. 

The  order  of  precedence  of  operators  at  the  same  parenthesis  level  is  [  |  (character  classes),  then 

♦  +  ?  (closures),  then  concatenation,  then  |  (alternation)  and  newline. 

EXAMPLES 

Search  a  file  for  a  fixed  string  using  fgrep: 

tutorial%  fgrep  Intro  /u8r/man/man3/«*3« 

Look  for  character  classes  using  grep: 

tutorial%  grep  ^(l-8]([CJMSNX])*  /usr/man/manl/**l 

Look  for  alternative  patterns  using  egrep: 

tutorial%  egrep  ^(SallyjFred)  (SmithjJonesjParker)*  telephonedist 

To  get  the  filename  displayed  when  only  processing  a  single  file,  use  fdevlnull  as  the  second  file 
in  the  list: 

tutorial%  grep  *SalIy  Parker*  telephoneJist  /dev/null 

SEE  ALSO 


vi(l) 

visual  display-oriented  editor  based  on  ex(l) 

ex(l) 

line-oriented  text  editor  based  on  ed(l) 

ed(l) 

primitive  line-oriented  text  editor 

sed(i) 

stream  editor 

awk(l) 

pattern  scanning  and  text  processing  language 

sh(l) 

Bourne  Shell 
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DIAGNOSTICS 

Exit  status  is  0  if  any  matches  are  found,  1  if  none,  2  for  syntax  errors  or  inaccessible  files. 

BUGS 

Lines  are  limited  to  256  characters;  longer  lines  are  truncated. 

Ideally  there  should  be  only  one  grep,  but  for  historical  reasons  there  are  three  different  versions 
each  with  a  slightly  different  set  of  options  and  syntaxes. 
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NAME 

groups  —  show  group  memberships 

SYNOPSIS 

groups 

DESCRIPTION 

Groups  displays  the  groups  to  which  you  belong.  Each  user  belongs  to  a  group  specified  in  the 
password  file  /etc/passwd  and  possibly  to  other  groups  as  specified  in  the  file  /etc/ group.  If  you 
do  not  own  a  file  but  belong  to  the  group  which  it  is  owned  by  then  you  are  granted  group  access 
to  the  file. 

When  a  new  file  is  created  it  is  given  the  group  of  the  containing  directory. 

SEE  ALSO 

setgroups(2) 

FILES 

/etc/passwd,  /etc/group 
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NAME 

head  —  display  first  few  lines  of  specified  files 
SYNOPSIS 

head  |  —count]  [file  ...  [ 

DESCRIPTION 

Head  copies  the  first  count  lines  of  the  specified  file(s),  or  of  the  standard  input  if  no  filename  is 
given,  to  the  standard  output.  The  default  value  of  count  is  10  lines. 

When  more  than  one  file  is  specified,  head  places  a  marker  at  the  start  of  each  file  which  looks 
like: 

==>  filename  <==■ 

Thus,  a  common  way  to  display  a  set  of  short  files,  identifying  each  one,  is: 
gaia%  head  -0009  fllel  flIeO  ... 

EXAMPLE 

gaia%  head  -4  /usr/inan/manl/{cat,head,tall}.l 

==>  /usr/man/manl/cat.l  <== 

,TH  CAT  1  "2  June  lOSS" 

.SH  NAME 

cat  —  concatenate  and  display 
.SH  SYNOPSIS 

==>  /usr/man/manl/head.l  <— » 

.TH  IffiAD  1  "24  August  1983” 

.SH  NAME 

head  —  display  first  few  lines  of  specified  files 
.SH  SYNOPSIS 

==>  /usr/man/manl/tail.l  <==» 

.TH  TAIL  1  "27  April  1983" 

.SH  NAME 

tail  —  display  the  last  part  of  a  file 
.SH  SYNOPSIS 

SEE  ALSO 

more(l),  tail(l),  cat(l) 
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NAME 

help  —  ask  for  help 
SYNOPSIS 

/usr/BCCs/help  jargs] 

DESCRIPTION 

Help  finds  information  to  explain  a  message  from  a  command  or  explain  the  use  of  a  command. 
Zero  or  more  arguments  may  be  supplied.  If  no  arguments  are  given,  help  will  prompt  for  one. 

The  arguments  may  be  either  message  numbers  (which  normally  appear  in  parentheses  following 
messages)  or  command  names,  of  one  of  the  following  types: 

type  1  Begins  with  non-numerics,  ends  in  numerics.  The  non-numeric  prefix  is 
usually  an  abbreviation  for  the  program  or  set  of  routines  which  produced 
the  message  (for  example,  geft,  for  message  6  from  the  get  command). 

type  2  Does  not  contain  numerics  (as  a  command,  such  as  get) 

type  3  Is  all  numeric  (for  example,  212) 

The  response  of  the  program  will  be  the  explanatory  information  related  to  the  argument,  if 
there  is  any. 

When  all  else  fails,  try  /usr/sccs/help  stuck. 

FILES 

/usr/lib/help  directory  containing  files  of  message  text. 

DIAGNOSTICS 

Use  help{l)  for  explanations. 
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NAME 

hostid  —  print  identifier  of  current  host  system 

SYNOPSIS 

hostid 

DESCRIPTION 

The  hostid  command  prints  the  identifier  of  the  current  host  in  hex.  This  numeric  value  is 
unique  across  all  Sun  hosts, 

SEE  ALSO 

get  hostid  (2) 
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NAME 

hostname  —  set  or  print  name  of  current  host  system 
SYNOPSIS 

hostname  |  nameofhost  | 

DESCRIPTION 

The  hostname  command  prints  the  name  of  the  current  host,  as  given  before  the  “login”  prompt. 
The  super-user  can  set  the  hostname  by  giving  an  argument;  this  is  usually  done  in  the  startup 
script  /etc/rc. local. 

SEE  ALSO 

gethostname(2),  sethostname(2) 


o 
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NAME 

icontool  —  create  and  edit  icons  and  cursors 

SYNOPSIS 

Icontool  I  filename  ] 

OPTIONS 

icontool  accepts  the  SunWindows  generic  tool  arguments;  see  sun(oofe(l)  for  a  list  of  these  argu¬ 
ments. 

DESCRIPTION 

icontool  is  a  bitmap  editor  that  allows  you  to  create  small  images  such  as  icons  and  cursors. 
icontool  runs  in  the  SunWindows  environment  and  can  be  positioned  and  manipulated  in  the 
same  way  as  any  other  SunWindows  tool.  For  general  hints  on  using  SunWindows  tools,  see  gun- 
tools{l). 

When  invoked,  icontool  displays  a  window  consisting  of  several  subwindows: 

•  A  large  drawing  area  or  canvag  (on  the  left). 

•  A  small  proof  area  for  previewing  a  life-size  version  of  the  image  being  edited  (at  the  lower 
right). 

•  A  control  panel  showing  the  options  available  and  their  current  state. 

•  An  area  for  status  messages  (at  the  upper  right). 

Instructions  for  the  use  of  the  mouse  appear  above  the  canvas. 

Move  the  cursor  to  the  canvas,  press  and  hold  the  left  mouse  button,  and  move  the  mouse  as 
desired  to  draw  an  image.  As  you  draw,  an  enlarged  version  of  the  image  appears  in  the  canvas, 
while  a  life-sized  version  of  the  image  appears  in  the  preview  area.  To  “erase”  any  unwanted 
portions  of  the  image,  press  and  hold  the  center  mouse  button  while  moving  the  mouse  as 
desired.  Clicking  the  right  mouse  button  inside  the  canvas  will  undo  the  previous  operation. 

If  you  are  editing  a  cursor  image,  move  the  cursor  into  the  proof  area  to  turn  the  proof  image 
into  the  mouse  cursor.  This  effect  only  lasts  while  you  are  in  the  proof  area;  it  allows  you  to  test 
how  the  new  cursor  looks  during  “real”  use. 

Note  that  in  this  writeup,  the  term  “cursor”  refers  to  the  mouse  cursor,  while  the  term  “caret” 
indicates  the  current  type-in  position. 


CONTROL  PANEL 

The  control  panel  at  the  center  right  of  the  tool  window  lists  the  options  available  to  you. 

To  select  an  option,  position  the  cursor  on  the  desired  item  and  click  the  left  mouse  button. 

To  display  a  menu  for  an  item,  position  the  cursor  on  the  desired  item,  then  press  and  hold  the 
right  mouse  button.  To  select  an  alternative  from  the  menu,  point  at  the  desired  alternative  and 
release  the  mouse  button.  If  you  are  just  starting  out,  you  may  want  to  use  the  menus  until  you 
become  familiar  with  the  tool. 

Some  of  the  panel  options  are  buttons  which  you  press,  in  effect,  by  pointing  to  them  and  clicking 
the  left  mouse  button.  Load  and  Store  are  two  examples  of  buttons.  A  small  capsule-shaped  box 
encloses  each  button. 

Other  choices  give  you  a  set  of  alternatives  from  which  to  select.  You  can  cycle  through  a  set  of 
alternatives  for  a  given  item  by  pointing  to  the  item  label  and  repeatedly  clicking  the  left  mouse 
button. 

The  “painting  hand”  indicates  the  current  painting  mode.  Small  triangular  carets  indicate  the 
current  state  of  the  Size  and  grid  options  as  well  as  the  proof  background  pattern.  A  triangular 
caret  points  to  the  current  type-in  position;  this  can  be  either  the  File  field  or  the  Fill  field 


Sun  Release  2.0 


Last  change;  29  March  1985 


167 


ICONTOOL(l) 


USER  COMMANDS 


ICONTOOL(l) 


corresponding  to  the  Text  (“abc”)  painting  mode  (see  below). 

In  detail,  the  control  panel  options  are: 

File  Contains  the  name  of  the  file  where  the  current  image  resides.  To  use  a  different  file 
from  the  one  shown,  point  at  the  file  name,  click  the  left  mouse  button,  and  type  a  new 
file  name.  The  filename  defaults  to  the  filename  given  on  the  command  line. 

Entering  an  alphabetic  string  terminated  by  <ESC>  requests  filename  completion,  icon’ 
tool  searches  the  current  directory  for  files  whose  names  begin  with  the  string  you 
entered.  If  the  filename  search  locates  only  one  file,  that  file  will  be  loaded  in.  In  addi¬ 
tion,  typing  CTRL-L,  CTRL-S,  or  CTRL-Q  are  equivalent  to  pressing  the  Load,  Store,  or 
Quit  buttons,  respectively. 

Load  (Button)  Load  the  canvas  from  the  file  named  in  the  File  field. 

Store  (Button)  Store  the  current  image  in  the  file  named  in  the  File  field. 

Quit  (Button)  Terminate  processing.  Quitting  requires  a  confirming  click  of  the  left  mouse 
button. 

Size  Alter  the  canvas  size.  Choices  are  icon  size  (64  x  64  pixels)  or  cursor  size  (16  x  16  pixels). 
Default  is  icon  size. 

Grid  Display  a  grid  over  the  drawing  canvas,  or  turn  the  grid  off.  Default  is  *‘grid  off”. 

Clear  (Button)  Clear  the  canvas. 

Fill  (Button)  Fill  canvas  with  current  rectangular  fill  pattern. 

Invert  (Button)  Invert  each  pixel  represented  on  the  canvas. 

Paintbrush 

Select  from  among  five  modes  of  painting.  The  painting  hand  indicates  the  current  paint¬ 
ing  mode.  Point  at  the  desired  mode  and  click  the  left  mouse  button  to  move  the  paint¬ 
ing  hand.  The  current  painting  mode  remains  until  you  change  it.  Instructions  for  each 
painting  mode  appear  above  the  canvas.  The  painting  modes  are: 

dot  Paint  a  single  dot  at  a  time. 

line  Draw  a  line.  To  draw  a  line  on  the  canvas,  point  to  the  first  endpoint  of  the  line, 
and  press  and  hold  the  left  mouse  button.  While  holding  the  button  down,  drag 
the  cursor  to  the  second  endpoint  of  the  line.  Release  the  mouse  button. 

rectangle 

Draw  a  rectangle.  To  draw  a  rectangle  on  the  canvas,  point  to  the  first  corner  of 
the  rectangle  and  press  and  hold  the  left  mouse  button.  While  holding  the  but¬ 
ton  down,  drag  the  cursor  to  the  diagonally  opposite  corner  of  the  rectangle. 
Release  the  mouse  button. 

In  the  control  panel,  the  Fill  field  to  the  right  of  the  rectangle  indicates  the 
current  rectangle  fill  pattern.  Any  rectangles  you  paint  on  the  canvas  will  be 
filled  with  this  pattern. 

circle  Draw  a  circle.  To  draw  a  circle  on  the  canvas,  point  to  the  center  of  the  circle, 
and  press  and  hold  the  left  mouse  button.  While  holding  the  button  down,  drag 
the  cursor  to  the  desired  edge  of  the  circle.  Release  the  mouse  button. 

In  the  control  panel,  the  Fill  field  to  the  right  of  the  circle  indicates  the  current 
circle  fill  pattern.  Any  circles  you  paint  on  the  canvas  will  be  filled  with  this  pat¬ 
tern. 

abc  Insert  text.  To  insert  text,  move  the  painting  hand  to  “abc”  and  type  the 
desired  text.  Then  move  the  cursor  to  the  canvas  and  press  and  hold  the  left 
mouse  button.  A  box  will  appear  where  the  text  is  to  go.  Position  the  box  as 
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desired  and  release  the  mouse  button. 

In  addition,  you  can  choose  the  font  in  which  to  draw  the  text.  Point  at  the  Fill 
field  to  the  right  of  the  *‘abc”  and  either  click  the  left  mouse  button  to  cycle 
through  the  fonts  available  (watch  the  “abc”  change  as  you  do  this),  or  press 
and  hold  the  right  mouse  button  to  summon  up  a  menu  of  fonts. 

Load  This  is  the  rasterop  to  be  used  when  loading  a  file  in  from  disk.  See  the  SunWindowB 
Reference  Manual  for  more  details  on  rasterops. 

Fill  This  is  the  rasterop  to  be  used  when  filling  the  canvas.  The  source  for  this  operation  is 
the  rectangle  fill  pattern,  and  the  destination  is  the  canvas. 

Proof  This  is  the  rasterop  to  be  used  when  rendering  the  proof  image.  The  source  for  this 
operation  is  the  proof  image,  and  the  destination  is  the  proof  background. 

Proof  background 

The  proof  background  can  be  changed  to  allow  you  to  preview  how  the  image  will  appear 
against  a  variety  of  patterns.  The  squares  just  above  the  proof  area  show  the  patterns 
available  for  use  as  the  proof  background  pattern.  To  change  the  proof  background, 
point  at  the  desired  pattern  and  click  the  left  mouse  button. 

SEE  ALSO 

FILES 

/usr/bin/icontool 
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NAME 

indent  —  indent  and  format  C  program  source 
SYNOPSIS 

indent  input- file  [  output- file  |  [  — Innn  |  [  ^cnnn  [  (  — cdnnn  ]  (  — Innn  j  [  — dj  |  — ndj  ] 
(  —V  I  — nv  ]  [  —be  [  — nbc  j  [  — dnnn  )  [  — br  |  — bl  J 

DESCRIPTION 

Indent  is  intended  primarily  as  a  C  program  formatter.  Specifically,  indent: 

•  indents  code  lines 


•  aligns  comments 

•  inserts  spaces  around  operators  where  necessary 

•  breaks  up  declaration  lists  as  in  ‘int  a,b,c;\ 

Indent  does  not  break  up  long  statements  to  make  them  fit  within  the  maximum  line  length,  but 
does  flag  lines  that  are  too  long.  Lines  are  broken  so  that  each  statement  starts  a  new  line,  and 
braces  appear  alone  on  a  line  —  see  the  — br  option  to  inhibit  this.  Also,  an  attempt  is  made  to 
line  up  identifiers  in  declarations. 

The  fiags  which  can  be  specified  follow.  They  may  appear  before  or  after  the  file  names. 

NOTE:  If  you  specify  only  an  input-filCf  the  formatting  is  done  ‘in-place’,  that  is,  the  format* 
ted  file  is  written  back  into  input-file  and  a  ‘backup’  copy  of  input-file  is  written  in  the 
current  directory.  If  input-file  is  named  yusr/sre/file’,  the  backup  file  is  named  •Bfile, 

If  output-file  is  specified,  indent  checks  to  make  sure  it  is  different  from  input-file. 


OPTIONS 

The  options  listed  here  control  the  formatting  style  imposed  by  indent. 


— Innn 
— ennn 
—cdnnn 

— innn 
-dj -ndj 


— V,— nv 


—be,— nbc 


— dnnn 


Maximum  length  of  an  output  line.  The  default  is  75, 

The  column  in  which  comments  start.  The  default  is  33. 

The  column  in  which  comments  on  declarations  start.  The  default  is  for  these 
comments  to  start  in  the  same  column  as  other  comments. 

The  number  of  spaces  for  one  indentation  level.  The  default  is  4. 

— dj  left  justifies  declarations.  — ndj  indents  declarations  the  same  as  code. 
The  default  is  — ndJ. 

— V  turns  on  ‘verbose’  mode,  — nv  turns  it  off.  When  in  verbose  mode,  indent 
reports  when  it  splits  one  line  of  input  into  two  or  more  lines  of  output,  and 
gives  some  size  statistics  at  completion.  The  default  is  — nv. 

If  —be  is  specified,  then  a  newline  is  forced  after  each  comma  in  a  declaration, 
—nbc  turns  off  this  option.  The  default  is  —be. 

This  option  controls  the  placement  of  comments  which  are  not  to  the  right  of 
code.  Specifying  — d2  means  that  such  comments  are  placed  two  indentation 
levels  to  the  left  of  code.  The  default  -dO  lines  up  these  comments  with  the 
code.  See  the  section  on  comment  indentation  below. 


— br,— bl  Specifying  — bl  lines  up  complex  statements  like  this: 

{ 

code 

} 


170 


Last  change:  28  September  1984 


Sun  Release  2.0 


INDENT(l) 


USER  COMMANDS 


INDENT(l) 


Specifying  -bp  (the  default)  makes  them  look  like  this: 
if  (...){ 
code 

) 

FURTHER  DESCRIPTION 

You  may  set  up  your  own  ‘profile’  of  defaults  to  indent  by  creating  a  file  called  .indent.pro  in 
your  login  directory  and  including  whatever  switches  you  like.  If  indent  is  run  and  a  profile  file 
exists,  then  it  is  read  to  set  up  the  program’s  defaults.  Switches  on  the  command  line,  though, 
always  override  profile  switches.  The  profile  file  must  be  a  single  line  of  not  more  than  127  char¬ 
acters.  The  switches  should  be  separated  on  the  line  by  spaces  or  tabs. 

Multi-line  exprcBflions 

Indent  does  not  break  up  complicated  expressions  that  extend  over  multiple  lines,  but  it  usually 
correctly  indents  such  expressions  which  have  already  been  broken  up.  Such  an  expression  might 
end  up  looking  like  this: 
x  =« 

( 

(Arbitrary  parenthesized  expression) 

+ 

( 

(Parenthesized  expression) 

* 

(Parenthesized  expression) 

) 

); 

Comments 

Indent  recognizes  four  kinds  of  comments.  They  are:  straight  text,  ‘box’  comments,  UNDC-stylc 
comments,  and  comments  that  should  be  passed  through  unchanged.  The  action  taken  with  these 
various  types  are  as  follows; 

‘Box’  comments.  Indent  assumes  that  any  comment  with  a  dash  immediately  after  the  start  of 
comment  (that  is,  ’/*—’)  is  a  comment  surrounded  by  a  box  of  stars.  Each  line  of  such  a  com¬ 
ment  is  left  unchanged,  except  that  the  first  non-blank  character  of  each  successive  line  is  lined 
up  with  the  beginning  slash  of  the  first  line.  Box  comments  are  be  indented  (see  below). 

‘Unix-style'  comments.  This  is  the  type  of  section  header  which  is  used  extensively  in  the  UNIX 
system  source.  If  the  start  of  comment  (‘/*’)  appears  on  a  line  by  itself,  indent  assumes  that  it  is 
a  UNIX-style  comment.  These  are  treated  similarly  to  box  comments,  except  the  first  non-blank 
character  on  each  line  is  lined  up  with  the  of  the  ’/♦’. 

Unchanged  comments.  Any  comment  which  starts  in  column  1  is  left  completely  unchanged. 
This  is  intended  primarily  for  documentation  header  pages.  The  check  for  unchanged  comments 
is  made  before  the  check  for  UNK-style  comments. 

Straight  text.  All  other  comments  are  treated  as  straight  text.  Indent  fits  as  many  words 
(separated  by  blanks,  tabs,  or  newlines)  on  a  line  as  possible.  Straight  text  comments  are 
indented. 

Comment  indentation 

Box,  UNEX-style,  and  straight  text  comments  may  be  indented.  If  a  comment  is  on  a  line  with 
code  it  is  started  in  the  ‘comment  column’,  which  is  set  by  the  — ennn  command  line  parameter. 
Otherwise,  the  comment  is  started  at  nnn  indentation  levels  less  than  where  code  is  currently 
being  placed,  where  nnn  is  specified  by  the  — dnnn  command  line  parameter.  Indented  comments 
are  never  placed  in  column  1.  If  the  code  on  a  line  extends  past  the  comment  column,  the 
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comment  is  moved  to  the  next  line. 

DIAGNOSTICS  ^ 

Diagnostic  error  messages,  mostly  to  tell  that  a  text  line  has  been  broken  or  is  too  long  for  the 

output  line. 

FILES 

.indent. pro  profile  file 

BUGS 

Does  not  know  how  to  format  ‘long’  declarations. 
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NAME 

indxbib  —  make  inverted  index  to  a  bibliography 

SYNOPSIS 

indxbib  database 

DESCRIPTION 

Indxbib  makes  an  inverted  index  to  the  named  databases  (or  files)  for  use  by  lookbib{l)  and 
re/cr(l).  These  files  contain  bibliographic  references  (or  other  kinds  of  information)  separated  by 
blank  lines. 

A  bibliographic  reference  is  a  set  of  lines,  constituting  fields  of  bibliographic  information.  Each 
field  starts  on  a  line  beginning  with  a  followed  by  a  key-letter,  then  a  blank,  and  finally  the 
contents  of  the  field,  which  may  continue  until  the  next  line  starting  with 

Indxbib  is  a  shell  script  that  calls  two  programs:  f  ustf  lib  f  refer jmkey  and  /usrf  lib /refer /inv, 
mkey  truncates  words  to  6  characters,  and  maps  upper  case  to  lower  case.  It  also  discards  words 
shorter  than  3  characters,  words  among  the  100  most  common  English  words,  and  numbers 
(dates)  <  1900  or  >  2000.  These  parameters  can  be  changed  —  see  Refer  —  a  Bibliography  Sys¬ 
tem  in  the  Editing  and  Text  Processing  on  the  Sun  Workstation  document,  inv  creates  an  entry 
file  (.ia),  a  posting  file  (.ib),  and  a  tag  file  (.ic),  all  in  the  working  directory, 

FILES 

ir.ia,  j.ib,  a?.ic,  where  x  is  the  first  argument,  or  if  these  are  not  present,  then  i.ig,  x 
SEE  ALSO 

refer(l),  addbib(l),  sortbib(l),  roffbib(l),  lookbib(l) 

BUGS 

Probably  all  dates  should  be  indexed,  since  many  disciplines  refer  to  literature  written  in  the 
1800s  or  earlier. 
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NAME 

inews  —  submit  news  articles 
SYNOPSIS 

InewB  I  —h  I  — t  title  \  — n  newsgroupe  ]  [  — c  expiration  date  | 

InewB  — p  [  filename  ] 

InewB  — C  newsgroup 
DESCRIPTION 

Inews  submits  news  articles  to  the  USENET  news  network.  Inews  is  intended  as  a  raw  interface 
to  the  news  system,  not  as  a  human  user  interface.  Casual  users  should  probably  use  postnews{l) 
instead. 

The  first  form  of  inews  is  for  submitting  user  articles.  The  body  of  the  article  is  read  from  the 
standard  input.  A  title  must  be  specified  as  there  is  no  default.  Each  article  belongs  to  a  list  of 
newsgroups.  The  standard  list  of  newsgroups  is  used  if  the  list  is  not  specified  via  the  — n  option. 
On  the  Sun  system,  the  standard  subscription  list  is:  general,  alLgeneral,  generalf  aliannounce, 
fjunk,  Icontrol,  and  Hest.  If  you  wish  to  submit  an  article  in  multiple  newsgroups,  the  news- 
groups  must  be  separated  by  commas  and/or  spaces.  The  expiration  date  is  set  to  the  local 
default  if  not  otherwise  specified. 

When  posting  an  article,  the  environment  is  checked  for  information  about  the  sender.  If  NAME 
is  found,  its  value  is  used  for  the  full  name,  rather  than  the  system  value  obtained  from 
fetc/passwd.  This  is  useful  if  the  system  value  cannot  be  set,  or  when  more  than  one  person  uses 
the  same  login.  If  ORGANIZATION  is  found,  the  value  overrides  the  system  default  organization. 
This  is  useful  when  a  person  uses  a  guest  login  and  is  not  primarily  associated  with  the  organiza¬ 
tion  owning  the  machine. 

The  second  form  of  inews  is  for  receiving  articles  from  other  machines.  If  filename  is  given,  the 
article  is  read  from  the  specified  file;  otherwise  the  article  is  read  from  the  standard  input.  An 
expiration  date  need  not  be  present  and  a  receiva!  date  is  ignored  if  present. 

After  local  installation,  inews  transmits  the  article  to  all  systems  that  subscribe  to  the  news- 
groups  that  the  article  belongs  to. 

The  third  form  of  is  for  creating  new  newsgroups.  On  some  systems,  this  may  be  limited 

to  specific  users  such  as  the  super-user  or  news  administrator.  This  is  true  on  the  Sun  system. 

If  the  file  fusr/ lib /news/ recording  is  present,  it  is  taken  as  a  list  of  ‘recordings*  to  be  shown  to 
users  posting  news.  This  is  an  analogy  to  the  recording  you  hear  when  you  dial  information  in 
some  parts  of  the  country,  asking  you  if  you  really  wanted  to  do  this.  / usr/ lib/ news/ recording 
contains  lines  of  the  form: 

newsgroups  <tab>  filename 
for  example: 

net. all  net.recording  fa.all  fa.recording 

Any  user  posting  an  article  to  a  newsgroup  matching  the  pattern  on  the  left  is  shown  the  con¬ 
tents  of  the  file  on  the  right.  The  file  is  found  in  the  LIB  directory  (often  /usr /lib /news).  The 
user  is  then  told  to  hit  DEL  to  abort  or  RETURN  to  proceed.  The  intent  of  this  feature  is  to 
help  companies  keep  proprietary  information  from  accidently  leaking  out, 

OPTIONS 

—n  "  newsgroups^ 

specifies  a  list  of  newsgroups  to  which  the  articles  are  submitted.  Elements  in  the  list 
must  be  separated  by  commas  and/or  spaces.  The  expiration  date  is  set  to  the  local 
default  if  not  otherwise  specified, 

— f  [sender] 

Specifies  the  article’s  sender.  Without  this  flag,  the  sender  defaults  to  the  user’s  name. 
If  — f  is  specified,  the  real  sender’s  name  is  included  as  a  Sender  line. 
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— h  Headers  are  present  at  the  beginning  of  the  article,  and  these  headers  should  be  included 

with  the  article  header  instead  of  as  text.  This  mechanism  can  be  used  to  edit  headers 
and  supply  additional  nondefault  headers,  but  not  to  specify  certain  information,  such  as 
the  sender  and  article  ID  that  inewa  itself  generates. 


FILES 


/usr/spool/news/.sys.nnn  temporary  articles 
/usr/spool/news/ncu7ayrnapa/ar<»c/e_rto. 


/usr/spool/oldnews/ 
/usr/lib/ news/active 
/usr/lib/news/seq 
/usr/lib/news/history 
/  usr/lib /news/sys 


Articles 

Expired  articles 

List  of  known  newsgroups  and  highest  local  article  numbers  in  each. 
Sequence  number  of  last  article 
List  of  all  articles  ever  seen 
System  subscription  list 


SEE  ALSO 

mail(l),  binmail(l),  getdate(3),  news(5),  newsrc(5),  postnews(l),  readnews(l),  recnews(l),  send- 
news(8),  uucp(l),  uurec(8), 

Network  News  User’s  Guide  in  the  Beginner’s  Guide  to  the  Sun  Workstation. 
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NAME 

install  —  install  files 
SYNOPSIS 

Install  [  — c  j  (  —m  mode  ]  (  — o  owner  j  [  — g  group  ]  [  — s  |  binary  destination 
DESCRIPTION 

Binary  is  copied  to  destination.  If  destination  already  exists,  it  is  removed  before  binary  is 
copied.  If  the  destination  is  a  directory  then  binary  is  copied  into  file  destination/ binary. 

Install  refuses  to  move  a  file  onto  itself. 

Note:  install  has  no  special  privileges  since  it  simply  uses  cp  to  copy  files  from  one  place  to 
another.  The  implications  of  this  are: 

•  You  must  have  permission  to  read  binary, 

•  You  must  have  permission  to  copy  into  destination, 

•  You  must  have  permission  to  change  the  modes  on  the  final  copy  of  the  file  if  you  want  to  use 
the  — m  option  to  change  modes.  In  addition,  if  you  want  to  set  any  modes  (such  as  set-user¬ 
id),  you  must  be  super-user. 

•  You  must  be  super-user  if  you  want  to  use  the  — o  option  to  change  ownership. 

OPTIONS 

—c  Copy  binary  instead  of  moving  it.  In  fact,  install  always  copies  the  file,  but  the  — c  option 
is  retained  for  backwards  compatibility  with  old  system  shell  scripts  which  might  other¬ 
wise  break. 

— m  mode 

Specifies  a  different  mode  for  binary:  the  mode  for  destination  is  set  to  755  by  default. 

— o  owner 

Set  the  owner  of  the  destination  file  to  owner,  destination  is  changed  to  owner  root  by 
default. 

---g  group 

Set  the  group  ownership  of  the  destination  file  to  group,  destination  is  changed  to  group 
staff  by  default. 

— s  Strip  binary  files  after  it  is  installed  —  only  applicable  to  binary  files  in  n.ott^(5)  format. 

SEE  ALSO 

chmod(l),  cp(l),  mv(l),  strip(l),  chown(8) 

BUGS 

Should  be  possible  to  move  multiple  files  at  a  time,  like  or  cp(l). 

When  the  destination  is  a  directory,  install  simply  appends  the  entire  source  file  name  to  the 
directory  name,  instead  of  using  the  source  file  name’s  last  component  like  mt;(l)  or  cp(l). 
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NAME 

join  —  relational  database  operator 
SYNOPSIS 

Join  [  —an  ]  [  — e  string  |  [  — j[l[2|  m  [  (  — o  Hat  ]  (  — tc  |  filel  file2 
DESCRIPTION 

Join  forms,  on  the  standard  output,  a  join  of  the  two  relations  specified  by  the  lines  ot  fitel  and 
file2.  If  filel  is  the  standard  input  Is  used. 

Filel  and  file2  must  be  sorted  in  increasing  ASCII  collating  sequence  on  the  fields  on  which  they 
are  to  be  joined,  normally  the  first  in  each  line. 

There  is  one  line  in  the  output  for  each  pair  of  lines  in  filel  and  fileS  that  have  identical  join 
fields.  The  output  line  normally  consists  of  the  common  field,  then  the  rest  of  the  line  from  filel, 
then  the  rest  of  the  line  from  file2. 

Fields  are  separated  by  blanks,  tabs  or  newlines.  Multiple  separators  count  as  one,  and  leading 
separators  are  discarded. 

OPTIONS 

—an  The  parameter  n  can  be  one  of  the  values: 

1  produce  a  line  for  each  unpairable  line  m  file!. 

2  produce  a  line  for  each  unpairable  line  in  file2. 

3  produce  a  line  for  each  unpairable  line  in  both  filel  and  file2. 

The  normal  output  is  also  produced. 

— c  a  Replace  empty  output  fields  by  string. 

-j[l!2]  m 

Join  on  the  mth  field  of  file  n,  where  n  is  1  or  2.  If  n  is  missing,  use  the  mth  field  in 
each  file.  Note  that  join  counts  fields  from  1  instead  of  0  like  5or^(l)  does. 

— o  Hat  Each  output  line  comprises  the  fields  specifed  in  Hat,  each  element  of  which  has  the  form 
n.m,  where  n  is  a  file  number  and  m  is  a  field  number.  Note  that  join  counts  fields  from 
1  instead  of  0  like  ^or^(l)  does, 

— tc  Use  character  c  as  a  separator  (tab  character).  Every  appearance  of  c  in  a  line  is 

significant. 

SEE  ALSO 

sort(l),  comm(l),  awk(l),  uniq(l),  look(l) 

BUGS 

With  default  field  separation,  the  collating  sequence  is  that  of  sort  -6;  with  — t,  the  sequence  is 
that  of  a  plain  sort. 

The  conventions  of  ycm(l),  ccrl(l),  ccmm(l),  uni^(l),  look{l),  and  a«;i(l)  are  wildly  incongruous. 
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NAME 

kill  —  send  a  signal  to  a  process,  or  terminate  a  process 
SYNOPSIS 

kill  I  — sig  ]  processid  ... 

kill  -1 

DESCRIPTION 

Kill  sends  the  TERM  (terminate,  15)  signal  to  the  specified  processes.  If  a  signal  name  or 
number  preceded  by  is  given  as  first  argument,  that  signal  is  sent  instead  of  terminate  (see 
«5«'ec(2)).  The  signal  names  are  listed  by  using  the  —I  option,  and  are  as  given  in 
fusr/include/signal.h,  stripped  of  the  common  SIG  prefix. 

The  terminate  signal  vrill  kill  processes  that  do  not  catch  the  signal,  so  kill  ...  is  a  sure  kill, 
as  the  KILL  (9)  signal  cannot  be  caught.  By  convention,  if  process  number  0  is  specified,  all 
members  in  the  process  group  (that  is,  processes  resulting  from  the  current  login)  are  signaled 
(but  beware:  this  works  only  if  you  use  sA(l);  not  if  you  use  ca5(l).)  The  killed  processes  must 
belong  to  the  current  user  unless  he  is  the  super-user. 

To  shut  the  system  down  and  bring  it  up  single  user  the  super-user  may  send  the  initialization 
process  a  TERM  (terminate)  signal  by  ‘kill  1’;  see  ini<(8).  To  force  init  to  close  and  open  termi¬ 
nals  according  to  what  is  currently  in  /etc/ttys  use  ‘kill  -HUP  1’  (sending  a  hangup,  signal  1). 

The  shell  reports  the  process  number  of  an  asynchronous  process  started  with  (run  in  the 
background).  Process  numbers  can  also  be  found  by  using  ps(l). 

Kill  is  built  in  to  csA(l);  it  allows  job  specifiers,  such  as  kill  %...,  in  place  of  kill  arguments. 
See  c«A(l)  for  details. 

OPTIONS 

—1  Display  a  list  of  signal  names. 

SEE  ALSO 

csh(l),  ps(l),  kill(2),  sigvec(2) 

BUGS 

An  option  to  kill  process  groups  ala  killpg{2)  should  be  provided;  a  replacement  for  kill  0  for 
csh{l)  users  should  be  provided. 
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NAME 

last  —  indicate  last  logins  of  users  and  teletypes 
SYNOPSIS 

last  I  —number  ][  —t  filename  [  (  name  ...  j  [  tty  ...  | 

DESCRIPTION 

Last  looks  back  in  the  wtmp  file  which  records  all  logins  and  logouts  for  information  about  a  user, 
a  teletype  or  any  group  of  users  and  teletypes.  Arguments  specify  names  of  users  or  teletypes  of 
interest.  Names  of  teletypes  may  be  given  fully  or  abbreviated.  For  example  ‘last  0’  is  the  same 
as  ‘last  tty0\  If  multiple  arguments  are  given,  the  information  which  applies  to  any  of  the  argu¬ 
ments  is  printed.  For  example  ‘last  root  console’  would  list  all  of  "root’s"  sessions  as  welt  as  all 
sessions  on  the  console  terminal.  Last  displays  the  sessions  of  the  specified  users  and  teletypes, 
most  recent  first,  indicating  the  times  at  which  the  session  began,  the  duration  of  the  session,  and 
the  teletype  which  the  session  took  place  on.  If  the  session  is  still  continuing  or  was  cut  short  by 
a  reboot,  last  so  indicates. 

The  pseudo-user  reboot  logs  in  at  reboots  of  the  system,  thus 
last  reboot 

will  give  an  indication  of  mean  time  between  reboot. 

Last  with  no  arguments  displays  a  record  of  all  logins  and  logouts,  in  reverse  order. 

If  last  is  interrupted,  it  indicates  how  far  the  search  has  progressed  in  wtmp.  If  interrupted  with  a 
quit  signal  (generated  by  a  contro!-\)  last  indicates  how  far  the  search  has  progressed  so  far,  and 
the  search  continues. 

OPTIONS 

—number 

limit  the  number  of  entries  displayed  to  that  specified  by  number. 

— f  filename 

Use  filename  as  the  name  of  the  accounting  file  instead  of  /etcfwtmp. 

FILES 

/usr/adm/wtmp  login  data  base 

/usr/adm/shutdownlog  which  records  shutdowns  and  reasons  for  same 
SEE  ALSO 

utmp(5),  ac(8),  lastcomm(l) 
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NAME 

lastcomm  —  show  last  commands  executed  in  reverse  order 
SYNOPSIS 

lastcomm  [  command  name  ]  ...  [user  name]  ...  [terminal  name]  ... 

DESCRIPTION 

Lastcomm  gives  information  on  previously  executed  commands.  Lastcomm  with  no  arguments 
displays  information  about  all  the  commands  recorded  during  the  current  accounting  file’s  life¬ 
time.  If  called  with  arguments,  lastcomm  only  displays  accounting  entries  with  a  matching  com¬ 
mand  name,  user  name,  or  terminal  name. 

EXAMPLES 

tutorial%  lastcomm  a«out  root  ttydO 

would  produce  a  listing  of  all  the  executions  of  commands  named  a.out,  by  user  root  while  using 
the  terminal  ttydO.  and 

tutorial%  lastcomm  root 

would  produce  a  listing  of  all  the  commands  executed  by  user  root. 

For  each  process  entry,  lastcomm  displays  the  following  items  of  information: 

•  The  command  name  under  which  the  process  was  called. 

•  One  or  more  flags  indicating  special  information  about  the  process.  The  flags  have  the  follow¬ 
ing  meanings: 

F  The  process  performed  a  fork  but  not  an  exec, 

S  The  process  ran  as  a  set-user-id  program. 

D  The  process  dumped  memory. 

X  The  process  was  killed  by  some  signal. 

•  The  name  of  the  user  who  ran  the  process. 

•  The  terminal  which  the  user  was  logged  in  on  at  the  time  (if  applicable). 

•  The  amount  of  CPU  time  used  by  the  process  (in  seconds). 

•  The  date  and  time  the  process  exited. 

FILES 

/usr/adm/acct  accounting  file 

SEE  ALSO 

last(l),  sigvec(2),  acct(5),  core(5) 
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NAME 

leave  —  remind  you  when  you  have  to  leave 

SYNOPSIS 

leave  [[+jhhmm  ] 

DESCRIPTION 

Leave  sets  an  alarm  to  a  time  you  specify  and  will  tell  you  when  the  time  is  up.  Leave  waits 
until  the  specified  time,  then  reminds  you  that  you  have  to  leave.  You  are  reminded  5  minutes 
and  1  minute  before  the  actual  time,  at  the  time,  and  every  minute  thereafter.  Leave  disappears 
after  you  log  off. 

You  can  specify  the  time  in  on  of  two  ways,  namely  as  an  absolute  time  of  day  in  the  form  hhmm 
where  hk  is  a  time  in  hours  (on  a  12  or  24  hour  clock),  or  you  can  place  a  +  sign  in  front  of  the 
time,  in  which  case  the  time  is  relative  to  the  current  time,  that  is,  the  specified  number  of  hours 
and  minutes  from  now.  All  times  are  converted  to  a  12  hour  clock,  and  assumed  to  be  in  the 
next  12  hours. 

If  no  argument  is  given,  leave  prompts  with  "When  do  you  have  to  leave?".  Leave  exits  if  you 
just  type  a  newline,  otherwise  the  reply  is  assumed  to  be  a  time.  This  form  is  suitable  for  inclu¬ 
sion  in  a  .login  or  .projile. 

Leave  ignores  interrupts,  quits,  and  terminates.  To  get  rid  of  it  you  should  either  log  off  or  use 
kill  —0  and  its  process  id. 

SEE  ALSO 

calendar(l) 

EXAMPLES 

The  first  example  sets  the  alarm  to  an  absolute  time  of  day: 
tutorial/^  leave  1535 
Alarm  set  for  Wed  Mar  7  15:35:07  1984 

work  work  work  work 

tutorial%  Time  to  leave! 

The  second  example  sets  the  alarm  for  10  minutes  in  the  future: 
tutorial%  leave  +10 
Alarm  set  for  Wed  Mar  7  15:45:24  1984 

work  work  work  work 

tutorial%  Time  to  leave! 

work  work  work  work 

tutorial%  YouVe  going  to  be  late! 


BUGS 

Relative  time  does  not  work  as  described.  Currently  you  must  specify  relative  time  in  the  form 
+mmmm.  It  is  not  checked  against  a  12  hour  clock. 
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NAME 

lex  —  generator  of  lexical  analysis  programs 
SYNOPSIS 

lex  [  — tvfti  1  [  file  1  ••• 

DESCRIPTION 

Lex  generates  programs  to  be  used  in  simple  lexical  analyis  of  text.  The  input  files  (standard 
input  default)  contain  regular  expressions  to  be  searched  for,  and  actions  written  in  C  to  be  exe¬ 
cuted  when  expressions  are  found. 

A  C  source  program,  ’lex.yy.c’  is  generated,  to  be  compiled  thus: 
cc  iex.yy.c  —11 

This  program,  when  run,  copies  unrecognized  portions  of  the  input  to  the  output,  and  executes 
the  associated  C  action  for  each  regular  expression  that  is  recognized. 

OPTIONS 

— t  Place  the  result  on  the  standard  output  instead  of  in  file  lez,yy,c. 

—V  Print  a  one-line  summary  of  statistics  of  the  generated  analyzer.'* 

— n  Opposite  of  — v;  — n  is  default. 

— f  ‘Faster’  compilation:  don’t  bother  to  pack  the  resulting  tables;  limited  to  small  programs. 

EXAMPLE 

lex  lexcommands 

would  draw  lex  instructions  from  the  file  lexcommands,  and  place  the  output  in  lex.yyx 

%% 

[A— Z I  pu tc har(yy text |0[+  "a " — " A " ); 

[  i+$ 

(  |-|-  putchar(^  ^); 

is  an  example  of  lex.  This  program  converts  upper  case  to  lower,  removes  blanks  at  the  end  of 
lines,  and  replaces  multiple  blanks  by  single  blanks. 

SEE  ALSO 

yacc(l),  sed(l) 

The  paper,  LEX  -  A  Lexical  Analyzer  Generator,  in  the  Sun  Programming  Tools  Manual. 


182 


Last  change:  1  November  1983 


Sun  Release  2.0 


UNT(l) 


USER  COMMANDS 


LINT(l) 


NAME 

lint  —  a  C  program  verifier 
SYNOPSIS 

lint  [  — abehnuvxs  ]  [  — D  name^def  |  (  — D  name  [  j  — U  name  |  |  —I  dir  j  file  . . . 
lint  [  -C/t6  I  file  ... 

DESCRIPTION 

Lint  attempts  to  detect  features  of  the  C  program  files  that  are  likely  to  be  bugs,  non-portable, 
or  wasteful.  Lint  also  checks  the  type  usage  of  the  program  more  strictly  than  the  C  compiler. 
Lint  runs  the  C  preprocessor  as  its  first  phase. 

Among  the  things  which  are  currently  found  are  unreachable  statements,  loops  not  entered  at 
the  top,  automatic  variables  declared  and  not  used,  and  logical  expressions  whose  value  is  con¬ 
stant.  Moreover,  the  usage  of  functions  is  checked  to  find  functions  which  return  values  in  some 
places  and  not  in  others,  functions  called  with  varying  numbers  of  arguments,  and  functions 
whose  values  are  not  used. 

By  default,  it  is  assumed  that  all  the  files  are  to  be  loaded  together;  they  are  checked  for  mutual 
compatibility.  Function  definitions  for  certain  libraries  are  available  to  lint;  these  libraries  are 
referred  to  by  a  conventional  name,  such  as  — Im,  in  the  style  of  /d(l).  The  standard  C  library 
(— Ic)  is  Unfed  by  default.  Arguments  ending  in  An  are  also  treated  as  library  files. 

To  create  lint  libraries,  use  the  — C  option.  For  example 
tutorial%  lint  — Ccongresa  files  .  .  . 

where  files  are  the  C  sources  of  library  congress,  produces  a  file  llib-lcongressAn  in  the 
f  usr  J  lib  J  lint  directory  in  the  correct  library  format  suitable  for  /tnPing  programs  using 

— Icongress. 

OPTIONS 

a  Report  assignments  of  long  values  to  Int  variables. 

b  Report  break  statements  that  cannot  be  reached.  This  is  not  the  default  because,  unfor¬ 
tunately,  most  lex  and  many  yacc  outputs  produce  dozens  of  such  comments. 

c  Complain  about  casts  which  have  questionable  portability. 

h  Apply  a  number  of  heuristic  tests  to  attempt  to  intuit  bugs,  improve  style,  and  reduce 
waste, 

n  Do  not  check  compatibility  against  the  standard  library, 

u  Do  not  complain  about  functions  and  variables  used  and  not  defined,  or  defined  and  not 
used  (this  is  suitable  for  running  lint  on  a  subset  of  files  out  of  a  larger  program), 

V  Suppress  complaints  about  unused  arguments  in  functions. 

X  Report  variables  referred  to  by  extern  declarations,  but  never  used. 

*  Do  not  complain  about  structures  that  are  never  defined  (for  example,  using  a  structure 

pointer  without  knowing  its  contents.), 

— Dname=</c/ 

—l>name 

Define  name  to  the  preprocessor,  as  if  by  *#define’.  If  no  definition  is  given,  the  name  is 
defined  as 

— Uname 

Remove  any  initial  definition  of  name  in  the  preprocessor. 

—\dir  *#include*  files  whose  names  do  not  begin  with  7*  sire  always  sought  first  in  the  directory 

of  the  file  argument,  then  in  directories  named  in  —I  options,  then  in  the  /nsr/include 
directory. 


Sun  Release  2.0 


Last  change:  1  February  1985 


183 


LINT(l) 


USER  COMMANDS 


LINT(l) 


—Cltb  create  a  lint  library  with  name  lib  (see  DESCRIPTION  section). 

— use  lint  library  lib  from  the  /uer/lib/lint  directory. 

General  Comments 

The  routine  exit{2)  and  other  functions  which  do  not  return  are  not  understood;  this  causes  vari¬ 
ous  lies. 

Certain  conventional  comments  in  the  C  source  will  change  the  behavior  of  lint: 
/♦NOTREACHED*/ 

at  appropriate  points  stops  comments  about  unreachable  code. 

/♦VARARGSnV 

suppresses  the  usual  checking  for  variable  numbers  of  arguments  in  the  following  func¬ 
tion  declaration.  The  data  types  of  the  first  n  arguments  are  checked;  a  missing  n  is 
taken  to  be  0. 

/♦ARGSUSED*/ 

turns  on  the  — v  option  for  the  next  function. 

/♦LINTLIBRARY*/ 

at  the  beginning  of  a  file,  shuts  off  complaints  about  unused  functions  in  this  file. 

EXAMPLE 

The  following  tint  call: 

tutorial%  lint  — b  myfile 

checks  the  consistency  of  the  file  ‘myfile’.  The  — b  option  indicates  that  unreachable  break 
statements  are  to  be  checked. 


FILES 

/usr/lib/lint/lint[l2] 

/usr/lib/lint/llib-Ic.ln 

/usr/lib/lint/Ilib-!c 

/usr/lib/lint/llib-lm.ln 

/usr/lib/lint/llib-lm 

/usr/lib/lint/llib‘lmp.ln 

/usr/lib/lint/llib-lmp 

Iib-l*.ln 


programs 

declarations  for  standard  functions 
human-readable  version  of  above 
declarations  for  math  functions 
human-readable  version  of  above 
declarations  for  multiprecision  functions 
human-readable  version  of  above 
library  created  by  the  — C  option 


SEE  ALSO 
cc(l) 

Lini,  a  C  Program  Checker,  in  Programming  Tools  for  the  Sun  Workstation 

BUGS 

There  are  some  things  you  just  can't  get  tint  to  shut  up  about. 
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NAME 

lockscreen  —  maintain  window  context  until  “login*’ 

SYNOPSIS 

lockscreen  [  — c  ]  [  — n  1  [  -“r  ] 

DESCRIPTION 

Lockscreen  preserves  the  user’s  window  setup  and  context  when  the  machine  is  not  in  use*  When 
run,  the  dark  lockscreen  display  and  constantly  moving  Sun  Microsystems  logo  limit  phosphorus 
burn  of  the  video  display  that  might  otherwise  occur  from  running  the  same  window 
configuration  for  a  long  time. 

Lockscreen  is  executed  from  a  terminal  emulator  running  inside  the  SunWindows  system.  When 
any  keyboard  or  mouse  button  is  pressed,  the  dark  screen  is  replaced  by  an  option  panel  that 
displays  the  user  name,  a  dark  box,  and  a  prompt  for  the  user’s  password.  If  the  user  has  no 
password,  or  if  the  — n  option  is  used,  the  user’s  window  setup  is  immediately  restored. 

When  the  option  screen  appears: 

1)  Enter  the  user’s  password  to  return  to  the  Sunwindows  environment;  this  password  is 
not  echoed  on  the  screen,  or, 

2)  Point  to  the  black  box  and  click  the  left  button  to  return  to  the  dark  display. 

The  panel  also  allows  you  to  enter  a  different  user  name  by  pointing  to  the  Name:  field,  clicking 
the  left  button,  and  typing  in  the  name.  You  must  then  supply  the  appropriate  password. 

OPTIONS 

— e 

— n 
— r 

SEE  ALSO 

suntools(l),  login(l) 


Add  the  Exit  Desktop  choice  to  the  options  panel.  If  pointed  to  and  clicked,  the  Sunwin* 
dows  environment  is  exited  and  the  current  user  is  logged  out. 

No  password  is  required  to  reenter  the  window  environment. 

Allows  use  of  the  user  name  root.  Normally,  root  is  not  accepted  as  a  valid  user  name. 
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NAME 

login  —  sign  on 

SYNOPSIS 

login  [  username  ] 

DESCRIPTION 

Login  signs  username  on  to  the  system  initially;  login  may  also  be  used  at  any  time  to  change 
from  one  user  i,d.  to  another. 

If  you  use  login  without  an  argument,  login  requests  a  user  name,  and  a  password  if  appropriate. 
Echoing  is  turned  off  (if  possible)  during  the  typing  of  the  password,  so  it  will  not  appear  on  the 
written  record  of  the  session. 

After  a  successful  login,  accounting  files  are  updated,  the  user  is  informed  of  the  existence  of 
mail,  and  the  message  of  the  day  is  printed,  as  is  the  time  he  last  logged  in  (unless  he  has  a 
^kushlogin  file  in  his  home  directory  —  this  is  mainly  used  to  make  life  easier  for  non-human 
users,  such  as  uucp). 

Login  initializes  the  user  and  group  IDs  and  the  working  directory,  then  executes  a  command 
interpreter  (usually  either  eh{i)  or  csh{l))  according  to  specifications  found  in  a  password  file. 
Argument  0  of  the  command  interpreter  is  “-*sh”,  or  more  generally  the  name  of  the  command 
interpreter  with  a  leading  dash  (‘‘^”)  prepended. 

Login  also  initializes  the  environment  environ{S)  with  information  specifying  home  directory, 
command  interpreter,  terminal  type  (if  available)  and  user  name. 

If  the  file  fetcf  nologin  exists,  login  prints  its  contents  on  the  user’s  terminal  and  exits.  This  is 
used  by  8hutdown{S)  to  stop  logins  when  the  system  is  about  to  go  down. 

Login  is  recognized  by  ^A(l)  and  C9A(1)  and  executed  directly  (without  forking). 

Login  times  out  and  exits  if  its  prompt  for  input  is  not  answered  within  some  ‘reasonable’  time. 

When  the  Bourne  Shell  (^^(l))  starts  up,  it  reads  a  file  called  .profile  from  the  user’s  home  direc¬ 
tory.  When  the  C-Shell  {^A(l))  starts  up,  it  reads  a  file  called  .login  from  the  user’s  home  direc¬ 
tory,  and  reads  a  file  called  .cshrc  from  the  user’s  home  directory  every  time  a  new  C-Shell  is 
started.  Note  that  the  Shells  only  read  these  files  if  they  are  owned  by  the  person  who  is  logging 
in  —  these  files  are  not  read  when  login  is  being  used  to  change  user  i.d. 


FILES 


/etc/utmp 

/usr/adm/wtmp 

/usr/spool/mail/* 

/etc/motd 

/etc/passwd 

/etc/nologin 

.hushlogin 


accounting 

accounting 

mail 

message-of-the-day 
password  file 
stops  logins 
makes  login  quieter 


SEE  ALSO 

init(8),  getty(8),  mail(l),  passwd(l),  passwd(5),  environ(S),  shutdown(8) 

DIAGNOSTICS 

“Login  incorrect,”  if  the  name  or  the  password  is  bad  (or  mis- typed). 

“No  Shell”,  “cannot  open  password  file”,  “no  directory”:  ask  your  system  administrator  for  assis¬ 
tance. 
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NAME 

look  —  find  lines  in  a  sorted  list 
SYNOPSIS 

look  I  — df  I  string  (  file  ] 

DESCRIPTION 

Look  consults  a  sorted  file  and  prints  all  lines  that  begin  with  string. 

OPTIONS 

— d  ‘Dictionary’  order:  only  letters,  digits,  tabs  and  blanks  participate  in  comparisons. 

— f  Fold:  Upper  case  letters  compare  equal  to  lower  case. 

If  no  file  is  specified,  look  uses  /usr/ diet/ words  with  collating  sequence  — df. 

FILES 

/usr/dict/words 

SEE  ALSO 

sort(l),  grep(l) 


Q 
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NAME 

lookbib  —  find  references  in  a  bibliography 

SYNOPSIS 

lookbib  database 

DESCRIPTION 

A  bibliographic  reference  is  a  set  of  lines,  constituting  fields  of  bibliographic  information.  Each 
field  starts  on  a  line  beginning  with  a  followed  by  a  key-letter,  then  a  blank,  and  finally  the 
contents  of  the  field,  which  may  continue  until  the  next  line  starting  with 

Lookbib  uses  an  inverted  index  made  by  indxhih  to  find  sets  of  bibliographic  references.  It  reads 
keywords  typed  after  the  prompt  on  the  terminal,  and  retrieves  records  containing  all  these 
keywords.  If  nothing  matches,  nothing  is  returned  except  another  prompt. 

It  is  possible  to  search  multiple  databases,  as  long  as  they  have  a  common  index  made  by  indxhih. 
In  that  case,  only  the  first  argument  given  to  indxbib  is  specified  to  lookbib. 

If  lookbib  does  not  find  the  index  files  (the  .i[abc]  files),  it  looks  for  a  reference  file  with  the  same 
name  as  the  argument,  without  the  suffixes.  It  creates  a  file  with  a  \ig’  suffix,  suitable  for  use 
with  fgrep.  Lookbib  then  uses  this  fgrep  file  to  find  references.  This  method  is  simpler  to  use, 
but  the  .ig  file  is  slower  to  use  than  the  .i[abcl  allow  the  use  of  multiple  refer¬ 

ence  files. 


FILES 

ar.ia,  x.ib,  a^.ic,  where  z  is  the  first  argument,  or  if  these  are  not  present,  then  x.ig,  x 
SEE  ALSO 

refer(l),  addbib(l),  sortbib(l),  roffbib(l),  indxbib(l) 

BUGS 

Probably  all  dates  should  be  indexed,  since  many  disciplines  refer  to  literature  written  in  the 
1800s  or  earlier. 
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NAME 

lorder  —  find  ordering  relation  for  an  object  library 

SYNOPSIS 

lorder  file  . . . 

DESCRIPTION 

Give  lorder  one  or  more  object  or  library  archive  (see  flr(l))  files,  and  it  lists  pairs  of  object  file 
names  —  meaning  that  the  first  file  of  the  pair  refers  to  external  identifiers  defined  in  the  second 
—  to  the  standard  output,  border's  output  may  be  processed  by  <»orf(l)  to  find  an  ordering  of  a 
library  suitable  for  one-pass  access  by  /d(l). 

EXAMPLE 

This  brash  one-liner  intends  to  build  a  new  library  from  existing  .0  files, 
ar  cr  library  '  lorder  *.o  |  tsort' 

The  ran/»J(l),  command  converts  an  ordered  archive  into  a  randomly  accessed  library  and  makes 
lorder  unnecessary. 

SEE  ALSO 

tsort(l),  ld(l),  ar(l),  ranlib(l) 

BUGS 

The  names  of  object  files,  in  and  out  of  libraries,  must  end  with  ‘.o';  otherwise,  nonsense  results. 
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NAME 

!pq  —  spool  queue  examination  program 
SYNOPSIS 

Ipq  (  +[  num  ]  [  [  — 1  ]  [  —Vprinttr  ]  (  job  #  -♦  ]  (  ...  ] 

DESCRIPTION 

Ipq  examines  the  spooling  area  used  by  /pd(8)  for  printing  files  on  the  line  printer,  and  reports  the 
status  of  the  specified  jobs  or  all  jobs  associated  with  a  user. 

Lpq  reports  on  any  jobs  currently  in  the  queue  when  invoked  without  any  options.  See  the 
OPTIONS  section  below  for  a  list  of  options.  Arguments  supplied  that  are  not  recognized  as 
options  are  interpreted  as  user  names  or  job  numbers  to  filter  out  only  those  jobs  of  interest. 

For  each  job  submitted  (that  is,  invocation  of  fpr(l))  lpq  reports  the  user’s  name,  current  rank  in 
the  queue,  the  names  of  files  comprising  the  job,  the  job  identifier  (a  number  which  may  be  sup¬ 
plied  to  /prm(l)  for  removing  a  specific  job),  and  the  total  size  in  bytes.  The  —1  option  causes 
information  about  each  of  the  files  comprising  the  job  to  be  printed.  Normally,  only  as  much 
information  as  will  fit  on  one  line  is  displayed.  Job  ordering  is  dependent  on  the  algorithm  used 
to  scan  the  spooling  directory  and  is  supposed  to  be  FIFO  (First  in  First  Out).  File  names 
comprising  a  job  may  be  unavailable  (when  fpr(l)  is  used  as  a  sink  in  a  pipeline)  in  which  case  the 
file  is  indicated  as  ^(standard  input)’. 

If  lpq  warns  that  there  is  no  daemon  present  (that  is,  due  to  some  malfunction),  the  fpc(8)  com¬ 
mand  can  be  used  to  restart  the  printer  daemon, 

OPTIONS 

Lpq  reports  on  any  jobs  currently  in  the  queue  when  invoked  without  any  options. 

--Pprinter 

report  on  jobs  routed  to  the  specified  printer.  In  the  absence  of  the  — P  option,  the 
default  line  printer  is  used  (or  the  value  of  the  PRINTER  variable  in  the  environment). 

+nnn  display  the  spool  queue  until  it  empties.  Supplying  a  number  nnn  immediately  after  the 
+  sign  indicates  that  lpq  should  sleep  nnn  seconds  in  between  scans  of  the  queue. 

FILES 

/etc/termcap 
/etc/printcap 
/usr /spool/* 

/usr  /  spool  /*/cf* 

/usr/spooI/*/lock 

SEE  ALSO 

Ipr(l),  Iprm(l),  lpc(8),  lpd(8) 

BUGS 

The  -I-  option  doesn’t  wait  until  the  entire  queue  is  empty;  it  only  waits  until  the  local  machine’s 
queue  is  empty. 

Due  to  the  dynamic  nature  of  the  information  in  the  spooling  directory  lpq  may  report  unreliably. 

Output  formatting  is  sensitive  to  the  line  length  of  the  terminal;  this  can  result  in  widely-spaced 
columns. 

lpq  is  sometimes  unable  to  open  various  files  because  the  lock  file  is  malformed. 

DIAGNOSTICS 

waiting  for  printer  to  become  ready 

The  daemon  could  not  open  the  printer  device.  This  can  happen  for  a  number  of  rea¬ 
sons;  the  most  common  is  that  the  printer  is  turned  off-line.  This  message  can  also  be 
generated  if  the  printer  is  out  of  paper,  the  paper  is  jammed,  and  so  on.  The  actual 


for  manipulating  the  screen  for  repeated  display 

to  determine  printer  characteristics 

the  spooling  directory,  as  determined  from  printcap 

control  files  specifying  jobs 

the  lock  file  to  obtain  the  currently  active  job 
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reason  is  dependent  on  the  meaning  of  error  codes  returned  by  system  device  driver.  Not 
all  printers  supply  sufficient  information  to  distinguish  when  a  printer  is  off-line  or  having 
trouble  (for  example,  a  printer  connected  through  a  serial  line).  Another  possible  cause  of 
this  message  is  some  other  process,  such  as  an  output  filter,  has  an  exclusive  open  on  the 
device.  Your  only  recourse  here  is  to  kill  off  the  offending  program(s)  and  restart  the 
printer  with  Ipe, 

printer  is  ready  and  printing 

The  Ipg  program  checks  to  see  if  a  daemon  process  exists  for  printer  and  prints  the  file 
status.  If  the  daemon  is  hung,  a  super  user  can  use  Ipc  to  abort  the  current  daemon  and 
start  a  new  one. 

wsdtlng  for  host  to  come  up 

Indicates  that  there  is  a  daemon  trying  to  connect  to  the  remote  machine  named  host  in 
order  to  send  the  files  in  the  local  queue.  If  the  remote  machine  is  up,  Ipd  on  the  remote 
machine  is  probably  dead  or  hung  and  should  be  restarted  as  mentioned  for  Ipr. 

sending  to  host 

The  files  should  be  in  the  process  of  being  transferred  to  the  remote  host.  If  not,  the 
local  daemon  should  be  aborted  and  started  with  Ipe. 

Warning:  printer  Is  down 

The  printer  has  been  marked  as  being  unavailable  with  Ipe. 

Warning:  no  daemon  present 

The  tpd  process  overseeing  the  spooling  queue,  as  indicated  in  the  “lock”  file  in  that 
directory,  does  not  exist.  This  normally  occurs  only  when  the  daemon  has  unexpectedly 
died.  The  error  log  file  for  the  printer  should  be  checked  for  a  diagnostic  from  the 
deceased  process.  To  restart  an  tpd,  use 

%  Ipe  restart  printer 
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NAME 

Ipr  -  off  line  print 
SYNOPSIS 

Ipr  I  —Pprinter  ]  [  — #««m  ]  (  —Cclass  ]  [  —Jjob  j  |  — T<if/e  ]  [  — 1(  num]  ]  [  — ll34/on<  ] 

(— wnum  1  (  — r  1  (  — m  |  (  — h  ]  |  — ■  1  [  —filter^option  J  [filename  ...  ] 

DESCRIPTION 

Lpr  uses  a  spooling  daemon  to  print  the  named  files  when  facilities  become  available.  Lpr  reads 
the  stndard  input  if  no  files  are  specified. 

OPTIONS 

—Fprinitr 

Force  output  to  the  named  printer.  Normally,  the  default  printer  is  used  (site  depen¬ 
dent),  or  the  value  of  the  PRINTER  environment  variable  is  used, 

— #n«m 

Produce  multiple  copies  of  output,  using  n«m  as  the  number  of  copies  for  each  file 
named.  For  example, 

tutorial%  lpr  — #3  newJndex.c  print.lndex*c  more*c 

produces  three  copies  of  the  file  newAndeXmC ,  followed  by  three  copies  of  prini*index*e , 
etc.  On  the  other  hand, 

tutorial^  cat  new.lndex.c  print. Index«c  more.e  { lpr  --#3 

generates  three  copies  of  the  concatenation  of  the  files. 

— C  Print  cla9B  as  the  job  classification  on  the  burst  page.  For  example, 
tutorial%  lpr  —C  Operations  new.lndex.c 
replaces  the  system  name  (the  name  returned  by  kostnaTne{l))  with  ‘Operations’  on  the 
burst  page,  and  prints  the  file  new*indez*c , 

—Jjob  Print  job  as  the  job  name  on  the  burst  page.  Normally,  lpr  uses  the  first  file’s  name. 
title 

Use  title  instead  of  the  file  name  for  the  title  used  by  pr(l)* 

— l[num] 

Indent  output  num  spaces.  If  num  is  not  given,  eight  spaces  are  used  as  default. 

— 1234/<?nl 

Mount  the  specified  font  on  font  position  i.  The  daemon  will  construct  a  .railmag  file 
referencing  /usrf lib/ vfont/ name. size. 

—wnum 

Use  num  as  the  page  width  for  pr(l). 

— r  Remove  the  file  upon  completion  of  spooling. 

— m  Send  mail  upon  completion. 

— h  Suppress  printing  the  burst  page. 

— •  Create  a  symbolic  link  from  the  spool  area  to  the  data  files  rather  than  trying  to  copy 

them  (so  large  files  can  be  printed).  This  means  the  data  files  should  not  be  modified  or 
removed  until  they  have  been  printed.  In  the  absence  of  this  option,  files  larger  than  1 
Megabyte  in  length  are  truncated.  Note  that  the  — s  option  only  works  if  you  are 
specifically  naming  data  files  —  it  doesn’t  work  if  lpr  is  at  the  end  of  a  pipeline. 

filter^option 

The  following  single  letter  options  notify  the  line  printer  spooler  that  the  files  are  not 
standard  text  files.  The  spooling  daemon  will  use  the  appropriate  filters  to  print  the  data 
accordingly, 

— p  Use  pr(l)  to  format  the  files  (equivalent  to  print). 
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*-1  Print  control  characters  and  suppress  page  breaks. 

— t  The  files  contain  data  from  troff{l)  (cat  phototypesetter  commands). 

— n  The  files  contain  data  from  ditroff  (device  independent  troff). 

— d  The  files  contain  data  from  tex  (DVI  format  from  Stanford). 

— g  The  files  contain  standard  plot  data  as  produced  by  the  p/o^(3X)  routines  (see 

also  p/<?^(lG)  for  the  filters  used  by  the  printer  spooler). 

— V  The  files  contain  a  raster  image  for  devices  like  the  Versatec. 

— c  This  option  currently  is  unassigned. 

— f  Interpret  the  first  character  of  each  line  as  a  standard  FORTRAN  carriage  con¬ 

trol  character. 


FILES 

/etc/passwd 

/etc/printcap 

/usr/lib/Ipd* 

/usr/spool/* 

/usr/spool/*/cf* 

/usr/spool/*/df* 

/usr/spool/^/tf* 


personal  identification 
printer  capabilities  data  base 
line  printer  daemons 
directories  used  for  spooling 
daemon  control  files 
data  files  specified  in  “cf”  files 
temporary  copies  of  “cf*  files 


SEE  ALSO 

Ipq(l),  Iprm(l),  pr(l),  sym!ink(2),  printcap(5),  lpc(8),  lpd(8) 

DIAGNOSTICS 

Ipr;  copy  file  1b  too  large 

A  file  is  determined  to  be  too  ‘large*  to  print  by  copying  into  the  spool  area.  Use  the 
option  as  defined  above  to  make  a  symbolic  link  to  the  file  instead  of  copying  it.  A 
‘large*  file  is  approximately  1  Megabyte  in  this  system. 

Ipr;  prm^er:  unknown  printer 

The  printer  was  not  found  in  the  printcap  database.  Usually  this  is  a  typing  mistake; 
however,  it  may  indicate  a  missing  or  incorrect  entry  in  the  /etc/printcap  file. 

Ipr:  printer z  Jobs  queuedi  but  cannot  start  daemon. 

The  connection  to  Ipd  on  the  local  machine  failed.  This  usually  means  the  printer  server 
started  at  boot  time  has  died  or  is  hung.  Check  the  local  socket  /dev/printer  to  be  sure 
it  still  exists  (if  it  does  not  exist,  there  is  no  Ipd  process  running). 

Ipr:  print erz  printer  queue  Is  disabled 

This  means  the  queue  was  turned  off  with 
tutorial%  Ipc  disable  printer 

to  prevent  Ipr  from  putting  files  in  the  queue.  This  is  normally  done  by  the  system 
manager  when  a  printer  is  going  to  be  down  for  a  long  time.  The  printer  can  be  turned 
back  on  by  a  super-user  with  Ipc. 


If  the  — f  and  —a  Bags  are  combined  as  follows: 


Ipr  — fs  filename 

copies  the  file  to  the  spooling  directory  rather  than  making  a  symbolic  link. 

Placing  the  — s  flag  first,  or  writing  each  as  separate  arguments  makes  a  link  as  expected. 
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NAME 

Iprm  —  remove  jobs  from  the  line  printer  spooling  queue 
SYNOPSIS 

Iprm  [  — Pprm^er  1  [  —  ]  [  job  #,..](  user  ...  ) 

DESCRIPTION 

Lprm  removes  a  job,  or  jobs,  from  a  printer’s  spool  queue.  Since  the  spooling  directory  is  pro¬ 
tected  from  users,  using  Iprm  is  normally  the  only  method  by  which  a  user  may  remove  a  job. 

Lprm  without  any  arguments  will  delete  the  currently  active  job  if  it  is  owned  by  the  user  who 
invoked  Iprm, 

If  the  —  flag  is  specified,  iprm  will  remove  all  jobs  which  a  user  owns.  If  the  super-user  employs 
this  flag,  the  spool  queue  will  be  emptied  entirely.  The  owner  is  determined  by  the  user’s  login 
name  and  host  name  on  the  machine  where  the  Ipr  command  was  invoked. 

Specifying  a  user’s  name,  or  list  of  user  names,  will  cause  Iprm  to  attempt  to  remove  any  jobs 
queued  belonging  to  that  user  (or  users).  This  form  of  invoking  Iprm  is  useful  only  to  the  super- 
user. 

A  user  may  dequeue  an  individual  job  by  specifying  its  job  number.  This  number  may  be 
obtained  from  the  lpq{l)  program.  For  example: 

tutorial%  Ipq  — Plmagcn 

imagen  is  ready  and  printing 

Rank  Owner  Job  Files  Total  Size 

active  wendy  385  standard  input  35501  bytes 

tutorial%  Iprm  -<Pimagen  305 

Lprm  announces  the  names  of  any  files  it  removes  and  is  silent  if  there  are  no  jobs  in  the  queue 
which  match  the  request  list, 

Lprm  will  kill  off  an  active  daemon,  if  necessary,  before  removing  any  spooling  files.  If  a  daemon 
is  killed,  a  new  one  is  automatically  restarted  upon  completion  of  file  removals. 

The  — P  option  may  be  used  to  specify  the  queue  associated  with  a  specific  printer  (otherwise  the 
default  printer,  or  the  value  of  the  PRINTER  variable  in  the  environment  is  used), 

FILES 

/etc/printcap 
/usr /spool/* 

/usr/spool/*/lock 

SEE  ALSO 

Ipr(l),  Ipq(l),  lpd(8) 

DIAGNOSTICS 

Iprmi  printen  cannot  restart  printer  daemon 

The  connection  to  Ipd  on  the  local  machine  failed.  This  usually  means  the  printer  server 
started  at  boot  time  has  died  or  is  hung.  Check  the  local  socket  /dev/ printer  to  be  sure 
it  still  exists  (if  it  does  not  exist,  there  is  no  Ipd  process  running).  Use 

%  pB  ax  { fgrep  Ipd 

to  get  a  list  of  process  identifiers  of  running  Ipd’s.  The  Ipd  to  kill  is  the  one  which  is  not 
listed  in  any  of  the  “lock”  files  (the  lock  file  is  contained  in  the  spool  directory  of  each 
printer).  Kill  the  master  daemon  using  the  following  command. 

%  km  pid 


printer  characteristics  file 
spooling  directories 

lock  file  used  to  obtain  the  pid  of  the  current 
daemon  and  the  job  number  of  the  currently  active  job 
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Then  remove  fdev! printer  and  restart  the  daemon  (and  printer)  with  the  following  com¬ 
mands. 

%  rm  /dev/printer  %  /usr/lib/lpd 

Another  possibility  is  that  the  tpr  program  is  not  setuid  root,  setgid  epooling.  This  can 
be  checked  with 

%  Is  — Ig  /usr/ucb/lpr 

BUGS 

Since  there  are  race  conditions  possible  in  the  update  of  the  lock  file,  the  currently  active  job 
may  be  incorrectly  identified. 


Sun  Release  2.0 


Last  change:  7  March  1984 


195 


LS(1) 


USER  COMMANDS 


LS(1) 


NAME 

Is  —  list  contents  of  directory 

SYNOPSIS 

Is  I  — acdfgllqrstulACLFR  |  name  . . . 

DESCRIPTION 

For  each  name  which  is  a  directory,  Is  lists  the  contents  of  the  directory;  for  each  name  which  is 
a  file,  Is  repeats  its  name  and  any  other  information  requested.  By  default,  the  output  is  sorted 
alphabetically.  When  no  argument  is  given,  the  current  directory  is  listed.  When  several  argu¬ 
ments  are  given,  the  arguments  are  first  sorted  appropriately,  but  file  arguments  are  processed 
before  directories  and  their  contents. 

OPTIONS 

There  are  a  large  number  of  options: 

—a  List  all  entries;  in  the  absence  of  this  option,  entries  whose  names  begin  with  a  period  (.) 
are  not  listed. 

— c  Use  time  of  file  creation  for  sorting  or  printing, 

— d  If  argument  is  a  directory,  list  only  its  name;  often  used  with  -“1  to  get  the  status  of  a 

directory. 

— f  Force  each  argument  to  be  interpreted  as  a  directory  and  list  the  name  found  in  each 
slot.  This  option  turns  off  —1,  — t,  — s,  and  — r,  and  turns  on  —a;  the  order  is  the  order 
in  which  entries  appear  in  the  directory. 

— g  Show  the  group  ownership  of  the  file  in  a  long  output. 

— i  For  each  file,  print  the  i-number  in  the  first  column  of  the  report, 

—1  List  in  long  format,  giving  mode,  number  of  links,  owner,  size  in  bytes,  and  time  of  last 

modification  for  each  file.  (See  below.)  If  the  file  is  a  special  file  the  size  field  will  instead 
contain  the  major  and  minor  device  numbers.  If  the  file  is  a  symbolic  link  the  pathname 
of  the  linked-to  file  is  printed  preceded  by 

— q  Display  non-graphic  characters  in  file  names  as  the  character  T;  this  is  the  default  when 
output  is  to  a  terminal. 

— r  Reverse  the  order  of  sort  to  get  reverse  alphabetic  or  oldest  first  as  appropriate. 

*-s  Give  size  in  kilobytes  of  each  file. 

— t  Sort  by  time  modified  (latest  first)  instead  of  by  name. 

— u  Use  time  of  last  access  instead  of  last  modification  for  sorting  (with  the  — t  option) 

and/or  printing  (with  the  —1  option). 

—1  Force  one  entry  per  line  output  format;  this  is  the  default  when  output  is  not  to  a  termi¬ 
nal. 

—A  Same  as  —a. 

— C  Force  multi-column  output;  this  is  the  default  when  output  is  to  a  terminal. 

— F  Mark  directories  with  a  trailing  */\  executable  files  with  a  trailing  **’,  symbolic  links  with 

a  trailing  and  AF.UNDC  domain  sockets  with  a  trailing 

— L  If  argument  is  a  symbolic  link,  list  the  file  or  directory  the  link  references  rather  than  the 

link  itself. 

— R  Recursively  list  subdirectories  encountered. 

INTERPRETATION  OF  LISTING 
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The  mode  printed  under  the  —1  option  contains  11  characters  interpreted  as  follows.  If  the  first 
character  is: 

d  entry  is  a  directory; 
b  entry  is  a  block-type  special  file; 
c  entry  is  a  character- type  special  file; 

1  entry  is  a  symbolic  link 
B  entry  is  an  AF_UNIX  domain  socket,  or 

—  entry  is  a  plain  file. 

The  next  9  characters  are  interpreted  as  three  sets  of  three  bits  each.  The  first  set  refers  to 
owner  permissions;  the  next  to  permissions  to  others  in  the  same  user-group;  and  the  last  to  all 
others.  Within  each  set  the  three  characters  indicate  permission  respectively  to  read,  to  write,  or 
to  execute  the  file  as  a  program.  For  a  directory,  ‘execute*  permission  is  interpreted  to  mean  per¬ 
mission  to  search  the  directory.  The  permissions  are  indicated  as  follows: 
r  the  file  is  readable; 

w  the  file  is  writable; 

X  the  file  is  executable; 

—  the  indicated  permission  is  not  granted. 

The  group-execute  permission  character  is  given  as  a  if  the  file  has  the  set-group-id  bit  set;  like¬ 
wise  the  user-execute  permission  character  is  given  as  s  if  the  file  has  the  set-user-id  bit  set. 

The  last  character  of  the  mode  (normally  ‘x*  or  — *)  is  t  if  the  1000  bit  of  the  mode  is  on.  See 
chmod{l)  for  the  meaning  of  this  mode. 

When  the  sizes  of  the  files  in  a  directory  are  listed,  a  total  count  of  blocks,  including  indirect 
blocks  is  printed. 

FILES 

/etc/passwd  to  get  user  id’s  for  7a  —1’. 

/etc/group  to  get  group  id’s  for  7a  — g’. 

BUGS 

Newline  and  tab  are  considered  printing  characters  in  file  names. 

The  output  device  is  assumed  to  be  80  columns  wide. 

The  option  setting  based  on  whether  the  output  is  a  teletype  is  undesirable  as  7^  —s’  is  much 
different  than  ‘1$  — b  j  Ipr’.  On  the  other  hand,  not  doing  this  setting  would  make  old  shell  scripts 
which  used  Is  almost  certain  losers. 
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NAME 

m4  macro  processor 

SYNOPSIS 

m4  [  file  •  • «  J 

DESCRIPTION 

M4  is  a  macro  processor  intended  as  a  front  end  for  Ratfor,  C,  and  other  languages.  Each  argu¬ 
ment  file  is  processed  in  order;  the  standard  input  is  read  if  there  are  no  arguments  or  if  an  argu¬ 
ment  is  The  processed  text  is  written  on  the  standard  output. 

Macro  calls  have  the  form 

name(argl,arg2,  .  . .  ,  argn) 

The  *(*  must  immediately  follow  the  name  of  the  macro.  If  a  defined  macro  name  is  not  followed 
by  a  *(',  it  is  deemed  to  have  no  arguments.  Leading  unquoted  blanks,  tabs,  and  newlines  are 
ignored  while  collecting  arguments.  Potential  macro  names  consist  of  alphabetic  letters,  digits, 
and  underscore  where  the  first  character  is  not  a  digit. 

Left  and  right  single  quotes  ')  are  used  to  quote  strings.  The  value  of  a  quoted  string  is  the 
string  stripped  of  the  quotes. 

When  a  macro  name  is  recognized,  its  arguments  are  collected  by  searching  for  a  matching  right 
parenthesis.  Macro  evaluation  proceeds  normally  during  the  collection  of  the  arguments,  and  any 
commas  or  right  parentheses  which  happen  to  turn  up  within  the  value  of  a  nested  call  are  as 
effective  as  those  in  the  original  input  text.  After  argument  collection,  the  value  of  the  macro  is 
pushed  back  onto  the  input  stream  and  rescanned. 

M4  makes  available  the  following  built-in  macros.  They  may  be  redefined,  but  once  this  is  done 
the  original  meaning  is  lost.  Their  values  are  null  unless  otherwise  stated. 

define  The  second  argument  is  installed  as  the  value  of  the  macro  whose  name  is  the  first 
argument.  Each  occurrence  of  $n  in  the  replacement  text,  where  n  is  a  digit,  is 
replaced  by  the  n-th  argument.  Argument  0  is  the  name  of  the  macro;  missing  argu¬ 
ments  are  replaced  by  the  null  string. 

undefine  removes  the  definition  of  the  macro  named  in  its  argument. 

ifdef  If  the  first  argument  is  defined,  the  value  is  the  second  argument,  otherwise  the  third. 
If  there  is  no  third  argument,  the  value  is  null.  The  word  unix  is  predefined  on  UNIX 
versions  of  m4- 

changequote 

Change  quote  characters  to  the  first  and  second  arguments.  Changequote  without 
arguments  restores  the  original  values  (that  is,  '  ^). 

M4  maintains  10  output  streams,  numbered  0-9.  The  final  output  is  the  concatena¬ 
tion  of  the  streams  in  numerical  order;  initially  stream  0  is  the  current  stream.  The 
divert  macro  changes  the  current  output  stream  to  its  (digit-string)  argument.  Out¬ 
put  diverted  to  a  stream  other  than  0  through  9  is  discarded. 

causes  immediate  output  of  text  from  diversions  named  as  arguments,  or  all  diver¬ 
sions  if  no  argument.  Text  may  be  undiverted  into  another  diversion.  Undiverting 
discards  the  diverted  text. 

returns  the  value  of  the  current  output  stream. 

reads  and  discards  characters  up  to  and  including  the  next  newline. 

has  three  or  more  arguments.  If  the  first  argument  is  the  same  string  as  the  second, 
then  the  value  is  the  third  argument.  If  not,  and  if  there  are  more  than  four  argu¬ 
ments,  the  process  is  repeated  with  arguments  4,  6,  6  and  7.  Otherwise,  the  value  is 
either  the  fourth  string,  or,  if  it  is  not  present,  null. 


divert 


undivert 

divnum 

dnl 

ifelse 
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Incr  returns  the  value  of  its  argument  incremented  by  1.  The  value  of  the  argument  is 
calculated  by  interpreting  an  initial  digit-string  as  a  decimal  number. 

cval  evaluates  its  argument  as  an  arithmetic  expression,  using  32-bit  arithmetic.  Opera¬ 
tors  include  +,  — ,  ♦,  /,  %,  "  (exponentiation);  relationals;  parentheses. 

len  returns  the  number  of  characters  in  its  argument. 

Index  returns  the  position  in  its  first  argument  where  the  second  argument  begins  (zero  ori¬ 
gin),  or  —1  if  the  second  argument  does  not  occur. 

substr  returns  a  substring  of  its  first  argument.  The  second  argument  is  a  zero  origin 

number  selecting  the  first  character;  the  third  argument  indicates  the  length  of  the 
substring.  A  missing  third  argument  is  taken  to  be  large  enough  to  extend  to  the  end 
of  the  first  string. 

translit  transliterates  the  characters  in  its  first  argument  from  the  set  given  by  the  second 
argument  to  the  set  given  by  the  third.  No  abbreviations  are  permitted. 

include  returns  the  contents  of  the  file  named  in  the  argument. 

slnclude  is  identical  to  include,  except  that  it  says  nothing  if  the  file  is  inaccessible. 

syscmd  executes  the  UNIX  command  given  in  the  first  argument.  No  value  is  returned. 

maketemp 

fills  in  a  string  of  XXXXX  in  its  argument  with  the  current  process  id. 

errprint  prints  its  argument  on  the  diagnostic  output  file. 

dumpdef  prints  current  names  and  definitions,  for  the  named  items,  or  for  all  if  no  arguments 
are  given. 

SEE  ALSO 

M4  —  A  Macro  Processor  ,  in  Programming  Toots  for  the  Sun  System, 
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NAME 

mai!  —  send  and  receive  mail 
SYNOPSIS 

mail  [  —V  )  [  — f  [  filename  ]  j  [  people  ...  ] 

INTRODUCTION 

Mail  is  an  interactive  facility  for  handling  electronic  mail.  Mail's  basic  unit  of  information  is  a 
message.  Mail  provides  facilities  for  sending  messages,  browsing  through  received  messages,  and 
sending  replies. 

Sending  mail.  To  send  a  message  to  one  or  more  other  people^  use  mail  with  arguments  which 
are  the  names  of  people  to  send  to.  The  people  arguments  can  be  the  names  of  users  on  your 
own  system,  or  they  can  be  network  addresses  —  see  below.  Then,  type  in  your  message,  fol¬ 
lowed  by  an  EOT  (control— D)  at  the  beginning  of  a  line.  The  section  labelled  Replying  to  or  oru 
ginating  mail,  describes  some  features  of  mail  available  to  help  you  compose  your  letter. 

The  —V  option  is  a  debugging  aid  for  mail  itself:  it  lets  you  see  if  your  mail  is  being  sent  out  OK. 

Reading  tnaiL  If  you  use  mail  without  arguments,  it  displays  a  one-line  header  for  each  mes¬ 
sage.  The  ‘current  message^  is  initially  the  first  message  (numbered  1);  you  can  display  it  with 
the  print  command  (abbreviated  p).  You  can  move  among  the  messages:  use  the  *-f-*  command 
to  move  forward  a  message,  the  ’  command  to  move  back  a  message,  and  simple  numbers  to 
address  a  particular  message. 

Disposing  of  mail.  After  examining  a  message  you  can  delete  (d)  the  message  or  reply  (r)  to 
it.  If  you  accidentally  delete  a  message,  you  do  have  recourse:  you  can  undelete  (u)  the  message 
by  giving  its  number,  or  you  can  exit  (x)  the  mail  session,  leaving  everything  as  it  was  before  you 
started.  Messages  deleted  during  the  mail  session  however,  usually  disappear  and  are  never  seen 
again. 

Specifying  messages.  Commands  such  as  print  and  delete  can  be  given  a  list  of  message- 
numbers  as  arguments  to  apply  to  a  number  of  messages  at  once.  Numbers  in  a  list  are 
separated  by  spaces.  Message-numbers  are  simple  numbers,  or  they  can  be  specified  as  a  range, 
that  is,  two  numbers  separated  by  a  minus  sign.  Thus: 

delete  1  2 

deletes  messages  1  and  2,  while: 

delete  1—5 

deletes  messages  1  through  5.  The  special  name  addresses  all  messages,  and  addresses  the 
last  message;  thus  the  top  command  (print  the  first  few  lines  of  a  message)  could  be  used  in: 

top  ♦ 

to  print  the  first  few  lines  of  all  messages. 

Replying  to  mail.  You  can  use  the  reply  (r)  command  to  respond  to  a  message,  followed  by 
the  text,  and  ending  with  an  EOT  (control-D)  or  a  period  alone  on  a  line.  There  are  some  varia¬ 
tions  of  the  reply  command: 

r  (the  straightforward  reply  command)  replies  to  the  person  who  sent  you  the  message. 

This  command  can  also  be  typed  as  replysender. 

R  (upper-case  R)  replies  to  everyone  who  got  the  original  message.  This  command  can  also 
be  typed  as  replyall. 

Also  see  the  replyall  variable.  Originating  mail  while  browsing.  You  can  use  the  mail 
command  (m)  to  originate  a  message  while  browsing.  While  you  are  composing  a  message,  you 
can  use  ‘escapes’  (usually  called  ‘tilde  escapes’)  to  get  mail  to  treat  such  lines  in  special  ways. 
For  instance,  typing  ‘'^m*  (alone  on  a  line)  places  a  copy  of  the  current  message  into  the  response, 
but  shifted  right  by  one  tabstop.  Other  escapes  set  up  subject  fields,  add  and  delete  recipients  to 
the  message,  and  allow  you  to  escape  to  an  editor  to  revise  the  message  or  to  a  shell  to  run  some 
commands.  These  options  are  described  in  the  summary  below. 
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Ending  a  mail  processing  session.  You  end  a  mail  session  with  the  quit  (q)  command. 
Messages  which  have  been  examined  but  not  deleted  go  to  your  mhox  file.  Messages  which  have 
been  deleted  are  discarded.  Unexamined  messages  are  retained.  The  — f  option  specifies  that 
mail  read  in  the  contents  of  your  mbox  (or  the  specified  file)  for  browsing;  when  you  quit  mail 
writes  undeleted  messages  back  to  this  file. 

Personal  and  systemwide  distribution  lists.  You  can  create  personal  distribution  lists  so 
that,  for  instance,  you  can  send  mail  to  ‘cohorts’  and  have  it  go  to  a  group  of  people.  Such  lists 
can  be  defined  by  placing  a  line  like: 

alias  cohorts  bill  ozalp  sklower  jkf  mark  coryrkridle 

in  the  file  ♦matVrc  in  your  home  directory.  You  can  nest  distribution  lists  so  that  a  distribution 
list  can  refer  to  other  distribution  lists,  which  finally,  refer  to  individual  people.  The  current  list 
of  such  aliases  can  be  displayed  by  the  alias  (a)  command. 

System  Distribution  Lists  System  wide  distribution  lists  can  be  created  by  editing 
/ usr/ lib/ aliases  f  see  a/zaffea(5)  and  sendmail{S);  these  are  kept  in  a  slightly  different  syntax.  In 
mail  you  send,  personal  aliases  are  expanded  in  mail  sent  to  others  so  that  they  can  reply  (lower 
case  r)  to  the  recipients.  System-wide  aliases  are  not  expanded  when  the  mail  is  sent,  but  any 
reply  returned  to  the  machine  will  have  the  system  wide  alias  expanded  as  all  mail  goes  through 
sendmaiL  If  you  edit  /ust/ lib/ aliases^  you  must  run  the  program  neu;a/inffes(8)  to  rebuild  the 
aliases  database. 

Network  mail  (ARPA,  UUCP).  Mail  to  sites  on  the  ARPA  or  UUCP  network  can  be  sent  using 
nam€@$ite  for  ARPA-net  sites  or  mackineluser  for  UUCP  sites,  provided  appropriate  gateways 
are  known  to  the  system.  Be  sure  to  escape  the  !  in  UUCP  sites  when  giving  it  on  a  csh  command 
line  by  preceding  it  with  a  \. 

Mail  has  a  number  of  options  which  can  be  set  in  the  .mailrc  file  to  alter  its  behavior;  thus 

set  askcc 

enables  the  ‘askcc’  (ask  for  carbon  copy)  feature.  These  options  are  summarized  below  in  the  sec¬ 
tion  labelled  Mail  Options. 

SUMMARY  OF  MAIL  COMMANDS 

This  summary  is  adapted  from  the  Mail  User^s  Guide. 

Each  mail  command  is  typed  on  a  line  by  itself.  Arguments  may  follow  the  command  word.  The 
command  word  need  not  be  typed  in  its  entirety  —  the  first  command  which  matches  the  typed 
prefix  is  used.  Commands  which  take  message  lists  as  arguments  use  the  next  message  forward 
which  satisfies  the  command’s  requirements  if  a  message-list  is  not  specified.  If  there  are  no  mes¬ 
sages  forward  of  the  current  message,  the  search  proceeds  backwards,  and  if  there  are  no  good 
messages  at  all,  mail  types  ‘No  applicable  messages’  and  aborts  the  command. 

—  |rtnn| 

Go  to  the  previous  message  and  print  it  out.  If  the  optional  numeric  argument  nnn  is 
specified,  go  to  the  nnn’th  previous  message  and  print  it. 

+  [nnn] 

Go  to  the  next  message  and  print  it  out.  If  the  optional  numeric  argument  nnn  is 
specified,  go  to  the  nnn’th  next  message  and  print  it. 

?  Print  a  brief  summary  of  commands, 
t  Shell  Command 

Execute  the  UNIX  Shell  Command  which  follows  the  !. 

alias  (a)  With  no  arguments,  print  out  all  currently-defined  aliases.  With  one  argument,  print 
out  that  alias.  With  more  than  one  argument,  add  the  users  named  in  the  second  and 
later  arguments  to  the  alias  named  in  the  first  argument. 

ehdlr  [  directory] 
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(c)  Change  the  user’s  working  directory  to  the  optional  directory  argument.  Change  to 
the  user’s  login  directory  if  directory  is  not  specified. 

delete  (d)  Takes  a  list  of  messages  as  argument  and  marks  them  all  as  deleted.  Deleted  mes¬ 
sages  are  not  saved  in  mboz,  nor  are  they  available  for  most  other  commands.  Messages 
deleted  in  the  current  mail  session  can  be  undeleted  with  the  undelete  command 
described  later. 

dp  (also  dt)  Delete  the  current  message  and  print  the  next  message.  If  there  is  no  next  mes¬ 
sage,  mail  says  ‘at  EOF.’ 

edit  (c)  Takes  a  list  of  messages  and  points  the  text  editor  at  each  one  in  turn.  You  can  edit 
the  message  freely,  with  two  exceptions:  you  must  not  touch  the  first  line  of  the  message 
header  (The  “From”  line),  and  you  must  leave  a  blank  line  at  the  end  of  the  message. 
When  you  exit  from  the  editor  (as  normal  for  the  editor:  ‘write’  and  ’quit’),  the  message 
is  read  back  in. 

exit  (ex  or  x)  Effects  an  immediate  return  to  the  Shell  without  modifying  the  user’s  system 
mailbox,  the  mboz  file,  or  the  edit  file  when  using  the  — f  option. 

folder  (fo)  The  folder  command  switches  to  a  new  mail  file  or  folder.  With  no  arguments,  it 
tells  you  which  file  you  are  browsing.  If  you  supply  a  filename  as  an  argument,  it  will 
write  out  changes  in  the  current  file,  and  access  the  named  file.  Some  special  conven¬ 
tions  are  recognized  for  the  argument.  #  indicates  the  previous  file,  %  indicates  your 
system  mailbox,  %user  indicates  the  user’s  system  mailbox,  &  means  your  ‘^/mboz  file, 
and  -^folder  means  a  file  in  your  folder  directory. 

folders 

List  the  names  of  the  folders  in  your  folders  directory. 

ft'om  (f)  Takes  a  list  of  messages  and  prints  their  message  headers, 

headers 

(h)  List  the  current  range  of  headers,  20  at  a  time  (fewer  lines  are  displayed  on  low-speed 
terminals).  If  you  want  to  see  another  group  of  headers,  you  must  type  a  number  that 
lies  within  that  group.  For  example, 

headers 

alone  displays  the  headers  of  the  first  20  messages.  To  see  headers  (say)  41  thru  60,  you 
can  type 

headers  45 

or  in  fact  any  number  that  lies  in  the  range  41  thru  60.  Also  see  the  s  command  below, 
which  scrolls  forwards  and  backwards  through  groups  of  headers. 

help  A  synonym  for  ? 

hold  (ho,  also  preserve)  Takes  a  message  list  and  marks  each  message  therein  to  be  saved  in 
the  user’s  system  mailbox  instead  of  in  mboz.  Does  not  override  the  delete  command, 

ignore  takes  a  list  of  character  strings  as  arguments.  Lines  in  the  header  of  mail  messages  that 
start  with  any  of  the  specified  character  strings  are  ignored. 

m^l  (m)  Takes  as  arguments  login  names  and  distribution  group  names  and  sends  mail  to 
those  people. 

next  (n  like  +  or  CR)  Goes  to  the  next  message  in  sequence  and  types  it.  With  an  argument 
list,  types  the  next  matching  message. 

preserve 

A  synonym  for  hold. 

print  (p)  Takes  a  message  list  and  types  out  each  message  on  the  user’s  terminal.  Typing  a 
print  command  with  a  capital  P  prints  even  ignored  headers. 
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quit  (q)  Terminate  the  mail  session,  saving  all  undeleted,  unsaved  messages  in  your  mbox  file 
in  your  login  directory,  preserving  all  messages  marked  with  hold  or  preserve  or  never 
referenced  in  your  system  mailbox,  and  removing  all  other  messages  from  your  system 
mailbox.  If  new  mail  has  arrived  during  the  mail  session,  mail  displays  a  message: 

You  have  new  mall 

If  you  quit  while  editing  a  mailbox  file  with  the  — f  flag,  mail  rewrites  the  edit  file.  Mail 
then  returns  to  the  Shell,  unless  the  rewrite  of  edit  file  fails,  in  which  case  the  user  can 
escape  with  the  exit  command. 

reply  (r)  Takes  a  message  list  and  sends  mail  to  each  message  author  just  like  the  mall  com¬ 
mand.  The  default  message  must  not  be  deleted, 

replyall 

Replies  to  all  members  on  a  distribution  list,  regardless  of  the  setting  of  the  replyall 
variable. 

replysender 

Reply  to  the  sender  of  the  message,  regardless  of  the  setting  of  the  of  the  replyall  vari¬ 
able. 

Reply  (upper-case  R)  replies  to  all  members  on  a  distribution  list. 

respond 

A  synonym  for  reply. 

Respond 

A  synonym  for  Reply. 

save  (s)  Takes  a  message  list  and  a  filename  and  appends  each  message  in  turn  to  the  end  of 
the  file.  The  filename  in  quotes,  followed  by  the  line  count  and  character  count  is  echoed 
on  the  user’s  terminal. 

set  (se)  With  no  arguments,  prints  all  variable  values.  Otherwise,  sets  option.  Arguments 
are  of  the  form: 

option— value 

or: 

option 

shell  (sh)  Invokes  an  interactive  version  of  the  shell. 

sise  Takes  a  message  list  and  prints  out  the  size  in  characters  of  each  message, 
source  (ao)  Accepts  mail  commands  from  a  file. 

subject 

(su)  works  like  the  from  command  but  works  with  subjects  instead  of  message  headers. 

Takes  a  message  list  and  prints  the  top  few  lines  of  each.  The  number  of  lines  printed  is 
controlled  by  the  variable  toplines  and  defaults  to  five. 

type  (t)  A  synonym  for  print. 

unalias 

Takes  a  list  of  names  defined  by  alias  commands  and  discards  the  remembered  groups  of 
users.  The  group  names  no  longer  have  any  significance. 

undelete 

(u)  Takes  a  message  list  and  marks  each  one  as  not  being  deleted. 

unset  Takes  a  list  of  option  names  and  discards  their  remembered  values;  the  inverse  of  set. 

visual  (v)  Takes  a  message  list  and  invokes  the  visual  editor  on  each  message.  Note  that  the 
cautions  given  for  the  edit  option  above  —  about  the  header  and  final  line  of  the  mes¬ 
sage  —  apply  here  as  well. 


Sun  Release  2.0 


Last  change:  25  March  1985 


203 


MAIL(l) 


USER  COMMANDS 


MAIL(l) 


write  (w)  is  similar  to  the  save  command,  but  write  removes  the  ‘From’  line  and  the  ‘Status’ 
line  from  the  header  of  the  messages,  whereas  save  leaves  those  lines  in  the  message. 

xlt  (x)  A  synonym  for  exit. 

X  Scrolls  forwards  and  backwards  through  groups  of  headers,  20  at  a  time  (fewer  lines  of 
headers  on  low-speed  terminals).  If  a  argument  is  given,  the  next  20  headers  are 
displayed,  and  if  a  ’  argument  is  given,  the  previous  20  headers  are  displayed. 

ESCAPE  SEQUENCES 

Here  is  a  summary  of  the  tilde  escapes,  which  are  used  when  composing  messages  to  perform  spe¬ 
cial  functions.  Tilde  escapes  are  only  recognized  at  the  beginning  of  lines.  The  name 
‘tilde  escape’  is  somewhat  of  a  misnomer  since  the  actual  escape  character  can  be  set  by  the 
option  escape. 

^!command 

Execute  the  indicated  shell  command,  then  return  to  the  message, 
name  ... 

Add  the  given  names  to  the  list  of  carbon  copy  recipients. 

"'d  Read  the  file  dead.letter  from  your  home  directory  into  the  message. 

Invoke  the  text  editor  on  the  message  collected  so  far.  After  the  editing  session  is 
finished,  you  may  continue  appending  text  to  the  message. 

messages 

Read  the  named  messages  into  the  message  being  sent.  If  no  messages  are  specified,  read 
the  current  message.  Also  see  the  command  which  does  the  same  thing  but  shifts 
the  message  right  by  one  tab  stop, 

"h  Edit  the  message  header  fields  by  typing  each  one  in  turn  and  allowing  the  user  to 
append  text  to  the  end  or  modify  the  field  by  using  the  current  terminal  erase  and  kill 
characters. 

messages 

Read  the  named  messages  into  the  message  being  sent,  shifted  right  one  tab.  If  no  mes¬ 
sages  are  specified,  read  the  current  message. 

Print  out  the  message  collected  so  far,  prefaced  by  the  message  header  fields. 

"'q  Abort  the  message  being  sent,  copying  the  message  to  deadnletter  in  your  home  directory 
if  save  is  set. 

'’r  filename 

Read  the  named  file  into  the  message. 

"b  string 

Make  the  named  string  become  the  current  subject  field, 
name  ... 

Add  the  given  names  to  the  direct  recipient  list. 

"'v  Invoke  an  alternate  editor  (defined  by  the  VISUAL  option)  on  the  message  collected  so 
far.  Usually,  the  alternate  editor  is  a  screen  editor.  After  you  quit  the  editor,  you  may 
resume  appending  text  to  the  end  of  your  message. 

"'w  filename 

Write  the  message  onto  the  named  file. 

^{command 

Pipe  the  message  through  the  command  as  a  filter.  If  the  command  gives  no  output  or 
terminates  abnormally,  retain  the  original  text  of  the  message.  The  command  /m/(l)  is 
often  used  as  command  to  rejustify  the  message. 
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‘"'string 

Insert  the  string  of  text  in  the  message  prefaced  by  a  single  If  you  have  changed  the 
escape  character,  then  you  should  double  that  character  in  order  to  send  it. 

MAIL  OPTIONS 

Options  are  controlled  via  the  set  and  unset  commands.  Options  may  be  either  binary,  in  which 
case  it  is  only  significant  to  see  whether  they  are  set  or  not,  or  string,  in  which  case  the  actual 
value  is  of  interest.  You  can  set  and  unset  options  during  a  mail  session,  or  you  can  place  the 
options  in  your  .mailrc  file  in  your  home  directory. 

Binary  Options.  The  binary  options  include  the  following; 

ftppend 

Messages  saved  in  mbox  are  appended  (the  default  case)  to  the  end  rather  than 
prepended.  This  is  set  in  /usr/lib/Mail.rc  on  version  7  systems. 

ask  Mail  prompts  you  for  the  subject  of  each  message  you  send.  If  you  respond  with  simply 
a  newline,  no  subject  field  is  sent. 

askcc  Mail  prompts  for  additional  carbon  copy  recipients  at  the  end  of  each  message.  Respond¬ 
ing  with  a  newline  indicates  your  satisfaction  with  the  current  list. 

autoprlnt 

The  delete  command  behaves  like  dp  —  thus,  after  deleting  a  message,  the  next  one  is 
typed  automatically. 

Ignore  Mail  ignores  interrupt  signals  from  your  terminal  and  echoes  them  as  @’s. 

hold  This  option  is  used  to  hold  messages  in  the  system  mailbox  by  default. 

metoo  Usually,  when  a  group  is  expanded  that  contains  the  sender,  the  sender  is  removed  from 
the  expansion.  Setting  metoo  includes  the  sender  in  the  group. 

nosave 

Prevents  mail  from  saving  messages  in  the  dead.letter  file  in  your  home  directory  on 
receipt  of  two  interrupts  (or  after  a  ’’q).  The  default  action  is  to  save  such  messages  in 
the  dead.letter  file. 

quiet  Suppress  printing  the  version  of  the  mail  program  when  first  invoked. 

replyall 

Alters  the  action  of  the  reply  and  Reply  commands:  reply  (lower-case  r)  normally 
replies  to  just  the  sender  of  the  message.  Reply  (upper-case  R)  normally  replies  to 
everyone  on  the  distribution  list.  Setting  the  replyall  variable  reverses  this  behavior  so 
that  r  (lower-case  r)  replies  to  everyone  on  the  distribution  list,  and  R  (upper-case  R) 
replies  to  just  the  sender*  This  feature  is  here  to  retain  compatibility  with  older  versions 
of  the  mail  system. 

String  Options.  The  following  options  have  string  values: 

EDITOR 

Pathname  of  the  text  editor  to  use  in  the  edit  command  and  '^c  escape.  If  not  defined, 
then  a  default  editor  is  used.  The  default  editor  is  /uar/ueb/ex. 

SHELL  Pathname  of  the  shell  to  use  in  the  !  command  and  the  escape.  A  default  shell  is  used 
if  this  option  is  not  defined.  The  default  shell  is  /bin/ceh. 

VISUAL 

Pathname  of  the  text  editor  to  use  in  the  visual  command  and  "v  escape. 

escape  If  defined,  the  first  character  of  this  option  gives  the  character  to  use  in  the  place  of  to 
denote  escapes. 

record  If  defined,  gives  the  pathname  of  the  file  used  to  record  all  outgoing  mail.  If  not  defined, 
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outgoing  mail  is  not  saved. 

toplines 

If  defined,  gives  the  number  of  lines  of  a  message  to  be  printed  out  with  the  top  com¬ 
mand;  normally,  the  first  five  lines  are  printed. 

crt  If  defined,  gives  the  number  of  lines  of  a  message  to  be  printed  before  mail  calls  up  the 
moTe{i)  utility  so  that  you  can  peruse  the  mail  messages  leisurely. 

EXAMPLES 

Send  mail  to  Wendy  on  her  system  called  ariel: 
angel%  mail  wendy@arlel 
Subject:  New  DBX  Manuals 

The  new  DBX  manual  pages  are  In  angel: /usr/man/manl/dbx.l 
"D 

EOT 

angel% 

Note  that  mail  asked  for  a  subject;  this  is  controlled  by  the  ask  option  in  the  .mailrc  file.  There 
is  an  example  of  such  a  file  later  on  in  this  section. 

Now  when  Wendy  is  working  on  her  system,  she  will  see  a  mail  notification: 
work,  work,  work 
You  have  new  mail. 
ariel%  mall 

Mail  version  2.17  12/26/82.  Type  ?  for  help 
"/usr/spool/mail/wendy":  1  message  1  new 

>N  1  cuthbert  Thu  Nov  3  10:03:01  11/266  "New  DBX  Manual  Pages’* 

&  Mail  signals  its  readiness  for  commands 

Carriage-return  means  read  next  message 

From  cuthbert  Thu  Nov  3  10:03:01  1983 
Date:  3  Nov  83  10:02:56  PST  (Thu) 

From:  cuthbert  (Cuthbert  Pouncetrifle) 

Subject:  New  DBX  Manual  Pages 
To:  wendy 
Status:  R 

The  new  DBX  manual  pages  are  in  angel:/usr/man/manl/dbx.l 


& 

Mail  signals  its  readiness  for  cornmands 
Carriage-return  means  read  next  message 

At  EOF 

Means  there  are  no  more  messages 

&  d 

Delete  this  message 

&  q 

Quit  from  the  mail  program 

ariel% 

Here  is  a  ^mailrc  file  in  which  you  can  set  options  to  control  mail^s  behavior: 
set  crt=30  ask 

ignore  via  apparently-to  date  from  status  received  message-id 

The  first  line  sets  the  crt  option  to  30  lines  —  if  there  are  messages  longer  than  this,  mail  calls 
up  more  to  page  through  the  message  in  30-line  chunks.  The  uk  option  makes  mail  ask  for  a 
subject  heading  every  time  you  send  mail  to  someone.  Finally,  the  second  line  says  to  ignore  any 
line  starting  with  any  of  the  character  strings  from  the  list  —  this  shortens  the  amount  of 
irrelevant  junk  that  appears  at  the  top  of  mail  messages. 
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Here  is  a  line  from  a  ,hgin  file  (oriented  to  the  C-Shell): 
set  mail=(10  /usr/spool/mail/$USER) 

This  set  command  instructs  the  C-Shell  to  look  in  /usr/ spool/ mail/iUSER  for  mail  every  10 
seconds  and  to  notify  you  if  there  is  mail  waiting  there.  In  the  absence  of  the  time  specification, 
the  Shell  looks  every  five  minutes.  ’ 


FILES 

/usr/spool/mail/* 

~/mbox 

“/.rnailrc 

/tmp/R# 

/usr/lib/Mail.help* 

/usr/lib/Mail.rc 

/bin/mail 

/usr/lib/sendmail 


post  office 
your  old  mail 

file  giving  initial  mail  commands 
temporary  for  editor  escape 
help  files 

system  initialization  file 
to  do  actual  mailing 
postman 


SEE  ALSO 

binmail(l),  fmt(l),  newaliases(8),  aliases(5),  sendmail(8),  mailaddr(7),  bifr(l) 

Mail  User’s  Guide  in  the  Beginner’s  Guide  to  the  Sun  Workstation,  which  gives  an  excellent 
introduction. 

For  senrfmoiV  installation  instructions,  see  the  Sun  System  Manager’s  Manual. 
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NAME 

make  —  maintain  program  groups 
SYNOPSIS 

make  [  — f  makefile  1  (  — 1  ]  (  ]  (  — n  )  [  — t  ]  (  — r  j  [  — s  )  [  — d  |  [  — p  ]  [  — S  j  (  — q  ]  file  . .. 

DESCRIPTION 

Make  executes  commands  in  makefile  to  update  one  or  more  target  files.  File  is  typically  a  pro¬ 
gram.  If  no  — f  option  is  present,  ^makefile’  and  ‘Makefile’  are  tried  in  order.  ‘Makefile’  with  a 
capital  M  is  the  preferred  choice  since  it  appears  towards  the  front  of  any  list  of  files  and  thus 
tends  to  stand  out.  If  makefile  is  make  reads  the  standard  input.  More  than  one  — f  option 
may  appear. 

Make  updates  a  target  if  it  depends  on  prerequisite  files  that  have  been  modified  since  the  target 
was  last  modified,  or  if  the  target  does  not  exist. 

Makefile  contains  a  sequence  of  entries  that  specify  dependencies.  The  first  line  of  an  entry  is  a 
blank-separated  list  of  targets,  then  a  colon,  then  a  list  of  prerequisite  files.  Text  following  a 
semicolon,  and  all  following  lines  that  begin  with  a  tab,  are  shell  commands  to  be  executed  to 
update  the  target.  If  a  name  appears  on  the  left  of  more  than  one  ‘colon’  line,  then  it  depends  on 
all  of  the  names  on  the  right  of  the  colon  on  those  lines,  but  only  one  command  sequence  may  be 
specified  for  it.  If  a  name  appears  on  a  line  with  a  double  colon  tx  then  the  command  sequence 
following  that  line  is  performed  only  if  the  name  is  out  of  date  with  respect  to  the  names  to  the 
right  of  the  double  colon,  and  is  not  affected  by  other  double  colon  lines  on  which  that  name  may 
appear. 

Two  special  forms  of  a  name  are  recognized.  A  name  like  library{file)  means  the  file  named  file 
stored  in  the  archive  named  library.  A  name  like  tibrary{{entry))  means  the  file  stored  in  archive 
library  containing  the  entry  point  entry. 

Sharp  and  newline  surround  comments,  except  on  lines  containing  shell  commands. 

The  following  makefile  says  that  program  depends  on  the  two  files  a.o  and  b.o  and  that  they  in 
turn  depend  on  .c  files  and  a  common  file  called  inch 

program:  a.o  b.o 

cc  a.o  b.o  —Im  — o  program 

a. o:  incl  a.c 

cc  — c  a.c 

b. o:  incl  b.c 

cc  — c  b.c 

Makefile  entries  of  the  form 
stringl  =5  string2 

are  macro  definitions.  Subsequent  appearances  of  or  ^{stringl}  are  replaced  by 

strings.  If  stringl  is  a  single  character,  the  parentheses  or  braces  are  optional. 

Make  infers  prerequisites  for  files  for  which  makefile  gives  no  construction  commands.  For 
example,  a  .c  file  may  be  inferred  as  prerequisite  for  a  file  and  be  compiled  to  produce  the 
file.  Thus  the  preceding  example  can  be  done  more  briefly: 

program:  a.o  b.o 

cc  a.o  b.o  — Im  — o  program 
a.o  b.o:  incl 

Prerequisites  are  inferred  according  to  selected  suffixes  listed  as  the  ‘prerequisites’  for  the  special 
name  .SUFFIXES;  multiple  lists  accumulate;  an  empty  list  clears  what  came  before.  Order  is 
significant;  the  first  possible  name  for  which  both  a  file  and  a  rule  as  described  in  the  next  para¬ 
graph  exist  is  inferred.  The  default  list  is 
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.SUFFIXES:  .out  .o  .c  .e  .r  .f  .y  .1  .s  .p 

The  rule  to  create  a  file  with  suffix  that  depends  on  a  similarly  named  file  with  suffix  ii  is 
specified  as  an  entry  for  the  ‘target’  .  Before  issuing  any  command,  makt  sets  certain  special 
macros: 

$@  is  set  to  the  name  of  the  file  to  be  ‘made’. 

$7  is  set  to  the  names  of  files  that  are  younger  than  the  target. 

ts  set  to  the  name  of  the  related  file  that  caused  the  action,  only  if  the  command  was 
generated  by  an  implicit  rule. 

$*  is  set  to  the  prefix  shared  by  the  current  and  dependent  filenames,  only  if  the  command 
was  generated  by  an  implicit  rule. 

For  example,  a  rule  for  making  optimized  ,o  files  from  .c  files  is 

.c.o: ;  cc  — c  — O  — o  $@  $*.c 

Certain  macros  are  used  by  the  default  inference  rules  to  communicate  optional  arguments  to 
any  resulting  compilations.  In  particular,  ‘CFLAGS’  is  used  for  cc(l)  options,  ‘FFLAGS’  for 
/77(1)  options,  ‘PFLAGS’  for  pc(l)  options,  and  ‘LFLAGS’  and  ‘YFLAGS’  for  fex  and  yacc(l) 
options.  In  addition,  the  macro  ‘MFLAGS’  is  filled  in  with  the  initial  command  line  options  sup¬ 
plied  to  make.  This  simplifies  maintaining  a  hierarchy  of  makefiles  as  one  may  then  invoke  make 
on  makefiles  in  subdirectories  and  pass  along  useful  options  such  as  — k. 

Command  lines  arc  executed  one  at  a  time,  each  by  its  own  shell.  A  line  is  printed  when  it  is 
executed  unless  the  special  target  .SQ/EINT  is  in  makefile^  or  the  first  character  of  the  command  is 

Commands  returning  nonzero  status  (see  »nfr<?(l))  cause  make  to  terminate  unless  the  special  tar¬ 
get  .IGNORE  is  in  makefile  or  the  command  begins  with  <tab><hyphen>. 

Interrupt  and  quit  cause  the  target  to  be  deleted  unless  the  target  is  a  directory  or  depends  on 
the  special  name  .PRECIOUS. 

OPTIONS 

— f  myfile 

myfile  is  the  name  of  the  file  to  use  for  make  commands  instead  of  the  default  ‘makefile’ 
or  ‘Makefile’. 

—I  Equivalent  to  the  special  entry  JGNORE:. 

— k  When  a  command  returns  nonzero  status,  abandon  work  on  the  current  entry,  but  con¬ 

tinue  on  branches  that  do  not  depend  on  the  current  entry. 

— n  Trace  and  print,  but  do  not  execute  the  commands  needed  to  update  the  targets. 

t  Touch,  that  is,  update  the  modified  date  of  targets,  without  executing  any  commands. 

— r  Equivalent  to  an  initial  special  entry  .SUFFIXES:  with  no  list. 

— *  Equivalent  to  the  special  entry  .SILENT:. 

— d  debug;  print  internal  state  after  each  command 

— p  print  internal  state  after  reading  Makefile 

•— q  determines  if  the  target  is  up  to  date  —  returns  a  zero  exit  status  if  it  is,  and  a  non-zero 

exit  status  otherwise. 

— S  undoes  the  effect  of  the  — k  option. 

FILES 

makefile.  Makefile 
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MAKE(i) 


SEE  ALSO 

sh(l),  touch(l),  f77(l),  pc(l) 

Make  —  A  Program  for  Maintaining  Computer  Programs,  in  Programming  Tools  for  the  Sun  Sgs- 
tern. 

BUGS 

Some  commands  return  nonzero  status  inappropriately.  Use  —I  to  overcome  the  difficulty. 
Commands  that  are  directly  executed  by  the  shell,  notably  ci(l),  are  ineffectual  across  newlines 
in  make. 

Make  should  recognize  names  of  libraries  in  the  dependency  entries,  for  example; 

grab:  -Im  grab.o 

cc  -o  grab  grab.o  -Im 
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NAME 

man  —  print  out  manual  pages;  find  manual  information  by  keywords 
SYNOPSIS 

man  [  —  |  1  — t  |  [  — P  path  ]  (  section  )  title  , . . 
man  — k  keyword  * .  * 
man  — f  file  . , . 

DESCRIPTION 

Man  displays  information  from  the  UNIX  System  manual  pages,  Man  can  be  asked  for  one  line 
descriptions  of  commands  specified  by  name,  or  for  all  commands  whose  description  contains  any 
of  a  set  of  keywords.  Man  can  also  provide  on-line  access  to  the  sections  of  the  printed  manual. 

Man’s  standard  behavior  when  neither  the  — k  nor  —f  option  is  specified  (see  OPTIONS  below)  is 
to  format  a  specified  set  of  manual  pages.  In  the  absence  of  any  specific  options  to  the  contrary, 
man  looks  for  already  formatted  manuals  in  the  /«^r/man/cof?  directories  and  uses  the  infor¬ 
mation  cached  there.  Otherwise,  man  must  format  the  pages  on  the  fly  —  in  this  case  you  get  a 
message  asking  you  to  wait  patiently. 

If  section  is  omitted,  man  searches  all  sections  of  the  manual,  giving -preference  to  commands 
over  subroutines  in  system  libraries,  and  prints  the  first  section  it  finds,  if  any. 

If  a  section  is  specified,  man  looks  in  that  section  of  the  manual  for  the  given  titles.  Section  is  an 
arabic  section  number  (‘3’  for  instance);  the  number  may  be  followed  by  a  single  letter  classifier 
(‘Ig’,  for  instance,  indicating  a  graphics  program  in  Section  l).  Finally,  section  can  be  one  of  the 
keywords  ‘public’,  ‘local’,  ‘old’,  or  ‘new’. 

If  the  standard  output  is  a  terminal,  or  if  you  use  the  —  flag,  man  pipes  its  output  through  caf(l) 
with  the  — B  option  to  crush  out  useless  blank  lines,  «/(l)  to  create  proper  underlines  for  different 
terminals,  and  through  more[\)  to  stop  after  each  page  on  the  screen.  Type  a  space  to  continue, 
and  a  control-D  to  scroll  11  more  lines  when  the  output  stops. 

OPTIONS 

— P  path 

Use  path  as  the  starting  pathname  for  the  manual  pages.  Manual  page  sections  must 
reside  in  pafA/man?  instead  of  in  /u^r/man/man? 

— k  keywords 

Display  a  one  line  synopsis  of  each  manual  section  whose  listing  in  the  table  of  contents 
contains  any  of  the  keywords. 

—f  filenames 

Attempt  to  locate  manual  sections  related  to  those  files,  and  display  the  table  of  contents 
lines  for  those  sections. 

— t  Use  troff  to  format  the  specified  section,  assuming  you  have  a  suitable  raster  output  dev¬ 

ice  which  can  actually  handle  troff^s  output. 

FILES 

/usr/man/man?/+  manual  pages  in  nroff/ troff  source 

/usr/man/cat?/^  formatted  manual  pages 

SEE  ALSO 

more(l),  ul(l),  whereis(l),  catman(8) 
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NAME 

mesg  —  permit  or  deny  messages 

SYNOPSIS 

mesg  [  n  1  I  y  1 

DESCRIPTION 

Mesg  with  argument  n  forbids  messages  via  ujrtle(l)  by  revoking 
the  user’s  terminal.  Mesg  with  argument  y  reinstates  permission, 
current  state  without  changing  it. 

FILES 

/dev/tty* 

SEE  ALSO 

write(l),  talk(l) 

DIAGNOSTICS 

Exit  status  is  0  if  messages  arc  receivable,  1  if  not,  2  on  error. 


non-user  write  permission  on 
All  by  itself,  mesg  reports  the 
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NAME 

mkdir  —  make  a  directory 

SYNOPSIS 

mkdir  dirname  •#« 

DESCRIPTION 

Mkdir  creates  directories.  Standard  entries,  *.*,  for  the  directory  itself,  and  for  its  parent,  are 
made  automatically. 

The  current  uma5A?(2)  setting  determines  the  mode  in  which  directories  are  created.  Modes  may 
be  modified  after  creation  by  using  chmod{iy 

Mkdir  requires  write  permission  in  the  parent  directory. 

SEE  ALSO 

chmod(l),  rmdir(l),  rm(l),  umask(2),  mkdir(2),  rmdir(2) 
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NAME 

mkstr  —  create  an  error  message  file  by  massaging  C  source 
SYNOPSIS 

mkstr  I  —  I  messagefile  prefix  file  ... 

DESCRIPTION 

Mkstr  creates  files  of  error  messages.  You  can  use  mkstr  to  make  programs  with  large  numbers 
of  error  diagnostics  much  smaller,  and  to  reduce  system  overhead  in  running  the  program  —  as 
the  error  messages  do  not  have  to  be  constantly  swapped  in  and  out. 

Mkstr  processes  each  of  the  specified  files,  placing  a  massaged  version  of  the  input  file  in  a  file 
whose  name  consists  of  the  specified  prefix  and  the  original  name.  A  typical  example  of  using 
mkstr  would  be: 

mkstr  pistrings  xx  *.c 

This  command  would  cause  all  the  error  messages  from  the  C  source  files  in  the  current  direc¬ 
tory  to  be  placed  in  the  file  pistrings  and  processed  copies  of  the  source  for  these  files  to  be 
placed  in  files  whose  names  are  prefixed  with  xx. 

To  process  the  error  messages  in  the  source  to  the  message  file,  mkstr  keys  on  the  string  ‘error("’ 
in  the  input  stream.  Each  time  it  occurs,  the  C  string  starting  at  the  is  placed  in  the  message 
file  followed  by  a  null  character  and  a  new-line  character;  the  null  character  terminates  the  mes¬ 
sage  so  it  can  be  easily  used  when  retrieved,  the  new-line  character  makes  it  possible  to  sensibly 
cat  the  error  message  file  to  see  its  contents.  The  massaged  copy  of  the  input  file  then  contains  a 
Iseek  pointer  into  the  file  which  can  be  used  to  retrieve  the  message,  that  is: 

char  efilnamej]  =•  "/usr/lib/pLstrings"; 

Int  efil  =  -1; 

error(al,  a2,  a3,  a4) 

{ 

char  buf|256|; 

If  (efil  <  0)  { 

efil  =  open(efilname,  0); 

If  (efil  <  0)  { 

oops: 

perror(efilname); 

exit(l); 

} 

if  (lseek(efil,  (long)  al,  0)  {j  read(efil,  buf,  256)  <=  0) 
goto  oops; 

printf(buf,  a2,  a3,  a4); 

} 

OPTIONS 

—  Place  error  messages  at  the  end  of  the  specified  message  file  for  recompiling  part  of  a  large 
mifc^^r’d  program. 

SEE  ALSO 

lscek(2),  xstr(l) 
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NAME 

more,  page  —  browse  through  a  text  file 
SYNOPSIS 

more  [  — cd6su  ]  [  —lines  \  [  +/jnenam6er  j  ( pattern  j  [  name  ...  ] 
page  I  —edflsu  ]  [  —lines  |  (  +linenumber  \  ( -b-f pattern  ]  [  name  ...  ] 

DESCRIPTION 

More  is  a  filter  which  displays  the  contents  of  a  text  file  one  screenful  at  a  time  on  a  video  termi¬ 
nal.  It  normally  pauses  after  each  screenful,  and  prints  ‘-More--’  at  the  bottom  of  the  screen. 
More  displays  another  line  if  you  type  a  carriage-return;  more  displays  another  screenful  if  you 
type  a  space. 

If  you  use  the  page  command  instead  of  the  more  command,  the  screen  is  cleared  before  each 
screenful  is  displayed  (but  only  if  a  full  screenful  is  being  displayed),  and  it  -  1  rather  than  it  -  2 
lines  are  displayed  in  each  screenful,  where  Ais  the  number  of  lines  the  terminal  can  display. 

More  looks  in  the  file  /etc/termcap  to  determine  terminal  characteristics,  and  to  determine  the 
default  window  size.  On  a  terminal  capable  of  displaying  24  lines,  the  default  window  size  is  22 
lines. 

More  looks  in  the  environment  variable  MORE  to  pre-set  any  flags  desired.  For  example,  if  you 
prefer  to  view  files  using  the  — c  mode  of  operation,  the  csh  command  ''setenv  MORE  -c”  or  the 
sh  command  sequence  "MORE^^’-c’ ;  export  MORE!'  would  cause  all  invocations  of  more  ,  includ¬ 
ing  invocations  by  programs  such  as  man  to  use  this  mode.  Normally,  the  user  will  place  the 
command  sequence  which  sets  up  the  environment  variable  in  the  .login  or  .profile  file. 

If  more  is  reading  from  a  file,  rather  than  a  pipe,  a  percentage  is  displayed  along  with  the  — 
More-  prompt.  This  gives  the  fraction  of  the  file  (in  characters,  not  lines)  that  has  been  read  so 
far. 

Other  sequences  which  may  be  typed  when  more  pauses,  and  their  effects,  are  as  follows  (» is  an 
optional  integer  argument,  defaulting  to  I)  : 

j<space> 

display  i  more  lines,  (or  another  screenful  if  no  argument  is  given) 

‘D  display  11  more  lines  (a  “scroll”).  If  i  is  given,  the  scroll  size  is  set  to  i. 
d  same  as  ‘D  (control-D) 

iz  same  as  typing  a  space  except  that  t,  if  present,  becomes  the  new  window  size, 

ts  skip  i  lines  and  print  a  screenful  of  lines 

»f  skip  I  screenfuls  and  print  a  screenful  of  lines 
q  or  Q  Exit  from  more. 

=  Display  the  current  line  number. 

v  Start  up  the  editor  vi  at  the  current  line. 

h  Help  command;  give  a  description  of  all  the  more  commands. 

j/expr  search  for  the  »-th  occurrence  of  the  regular  expression  expr.  If  there  are  less  than  i 
occurrences  of  ea:pr,  and  the  input  is  a  file  (rather  than  a  pipe),  the  position  in  the  file 
remains  unchanged.  Otherwise,  a  screenful  is  displayed,  starting  two  lines  before  the 
place  where  the  expression  was  found,  or  the  end  of  the  pipe,  whichever  comes  first.  The 
user’s  erase  and  kill  characters  may  be  used  to  edit  the  regular  expression.  Erasing  back 
past  the  first  column  cancels  the  search  command. 

in  search  for  the  I'-th  occurrence  of  the  last  regular  expression  entered. 
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*  (single  quote)  Go  to  the  point  from  which  the  last  search  started*  If  no  search  has  been 

performed  in  the  current  file,  this  command  goes  back  to  the  beginning  of  the  file. 

Icommand 

invoke  a  shell  with  command.  The  characters  *%'  and  in  "command”  are  replaced 
with  the  current  file  name  and  the  previous  shell  command  respectively.  If  there  is  no 
current  file  name,  is  not  expanded.  The  sequences  "\%"  and  "\!"  are  replaced  by 
and  respectively. 

i:n  skip  to  the  i-th  next  file  given  in  the  command  line  (skips  to  last  file  if  n  doesn’t  make 
sense) 

rp  skip  to  the  i-th  previous  file  given  in  the  command  line.  If  this  command  is  given  in  the 
middle  of  printing  out  a  file,  more  goes  back  to  the  beginning  of  the  file.  If  i  doesn’t  make 
sense,  more  skips  back  to  the  first  file.  If  more  is  not  reading  from  a  file,  the  bell  is  rung 
and  nothing  else  happens. 

:f  display  the  current  file  name  and  line  number. 

:q  or  :Q 

exit  from  more  (same  as  q  or  Q). 

(dot)  repeat  the  previous  command. 

The  commands  take  effect  immediately;  it  is  not  necessary  to  type  a  carriage  return.  Up  to  the 
time  when  the  command  character  itself  is  given,  the  user  may  type  the  line  kill  character  to  can¬ 
cel  the  numerical  argument  being  formed.  In  addition,  the  user  may  type  the  erase  character  to 
redisplay  the  -More-(xx%)  message. 

At  any  time  when  output  is  being  sent  to  the  terminal,  the  user  can  type  the  quit  key  (normally 
control— \).  More  stops  sending  output,  and  displays  the  usual  —More—  prompt.  The  user  may 
then  enter  one  of  the  above  commands  in  the  norma!  manner.  Unfortunately,  some  output  is  lost 
when  this  is  done,  due  to  the  fact  that  any  characters  waiting  in  the  terminal’s  output  queue  are 
flushed  when  the  quit  signal  occurs. 

More  sets  the  terminal  to  noecho  mode  so  that  the  output  can  be  continuous.  Thus  what  you 
type  does  not  show  on  your  terminal,  except  for  the  /  and  !  commands. 

If  the  standard  output  is  not  a  terminal,  more  acts  just  like  cat,  except  that  a  header  is  printed 
before  each  file  in  a  series. 

OPTIONS 

— /mes  Set  the  size  of  the  window  to  lines  lines  long  instead  of  the  default. 

— c  Display  each  page  by  redrawing  the  screen  instead  of  scrolling.  This  makes  it  easier  to 
read  text  while  more  is  writing.  This  option  is  ignored  if  the  terminal  does  not  have  the 
ability  to  clear  to  the  end  of  a  line. 

— d  Display  the  message  ‘Hit  space  to  continue,  Rubout  to  abort’  at  the  end  of  each  screen¬ 

ful.  This  is  useful  if  more  is  being  used  as  a  filter  in  some  setting,  such  as  a  class,  where 
users  are  unsophisticated. 

— f  Count  logical  rather  than  screen  lines.  That  is,  long  lines  are  not  folded.  This  option  is 

recommended  if  nroff  output  is  being  piped  through  ul,  since  the  latter  may  generate 
escape  sequences.  These  escape  sequences  contain  characters  which  would  ordinarily 
occupy  screen  postions,  but  which  do  not  print  when  they  are  sent  to  the  terminal  as 
part  of  an  escape  sequence.  Thus  more  may  think  that  lines  are  longer  than  they  actu¬ 
ally  are,  and  fold  lines  erroneously. 

—1  Do  not  treat  "L  (form  feed)  specially.  If  — /  is  not  used,  more  pauses  after  any  line  that 
contains  a  "L,  as  if  the  end  of  a  screenful  had  been  reached.  Also,  if  a  file  begins  with  a 
form  feed,  the  screen  is  cleared  before  the  file  is  printed. 
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— «  Squeeze  multiple  blank  lines  from  the  output,  and  replace  them  with  single  blank  lines. 

Especially  helpful  when  viewing  nroff  output,  this  option  maximizes  the  useful  informa¬ 
tion  present  on  the  screen. 

— u  Normally,  more  handles  underlining  such  as  produced  by  nroff  in  a  manner  appropriate 

to  the  particular  terminal:  if  the  terminal  can  perform  underlining  or  has  a  stand-out 
mode,  more  outputs  appropriate  escape  sequences  to  enable  underlining  or  stand-out 
mode  for  underlined  information  in  the  source  file.  The  — u  option  suppresses  this  pro¬ 
cessing. 

+/menumier 

Start  up  at  Itnenumber, 

-{•/pattern 

Start  up  two  lines  before  the  line  containing  the  regular  expression  pattern, 

EXAMPLES 

A  sample  usage  of  more  in  previewing  nroff  output  would  be 
nroff  -ms  -b2  doc.n  |  more  -s 

FILES 

/etc/termcap  Terminal  data  base 

/usr/lib/more.help  Help  file 

SEE  ALSO 

csh(l),  man(l),  script(l),  sh(l),  environ(5),  termcap(5) 
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NAME 

mt  —  magnetic  tape  manipulating  program 
SYNOPSIS 

mt  I  — f  iaptnamt  |  command  [  count  ] 

DESCRIPTION 

mt  sends  commands  to  a  magnetic  tape  drive.  If  tapename  is  not  specified,  the  environment  vari¬ 
able  TAPE  is  used;  if  TAPE  does  not  exist,  mt  uses  the  device  /dev/rmtlS.  Note  that  tapename 
must  reference  a  raw  (not  block)  tape  device.  By  default  mt  performs  the  requested  operation 
once.  Operations  may  be  performed  multiple  times  by  specifying  count. 

The  available  commands  are  listed  below.  Only  as  many  characters  as  are  required  to  uniquely 
identify  a  command  need  be  specified. 

eof,  wcof 

Write  count  end-of-file  marks  at  the  current  position  on  the  tape, 
fef  Forward  space  count  files, 

fgr  Forward  space  count  records, 

bsf  Back  space  count  files, 

her  Back  space  count  records. 

For  the  following  commands,  count  is  ignored: 
rewind 

Rewind  the  tape. 

offline,  rewoffl 

Rewind  the  tape  and  place  the  tape  unit  off-line, 
status  Print  status  information  about  the  tape  unit, 

retenslon 

Retension  the  tape. 

erase  Erase  the  entire  tape. 

mt  returns  a  0  exit  status  when  the  operation(s)  were  successful,  1  if  the  command  was  unrecog¬ 
nized,  and  2  if  an  operation  failed. 

FILES 

/dev/rmt^  Raw  magnetic  tape  interface 

/dev/rar*  Raw  Archive  cartridge  tape  interface 
/dev/rst*  Raw  SCSI  tape  interface 

SEE  ALSO 

mtio(4),  dd(l),  ioctl(2),  environ(5) 

BUGS 

Not  all  devices  support  all  commands.  For  example,  ar{is)  and  af{4s)  currently  do  not  support 
the  fgri  hstf  or  bar  commands;  but  they  are  the  only  only  ones  that  currently  support  the 
retenslon  and  rewind  commands. 
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NAME 

mv  move  or  rename  files 
SYNOPSIS 

mv  [  — 1 1  1  1  [  ^  I 

mv  [  — 1 1  1  1  1  ^  i  directoryl  directory2 

mv  [  — 1  ]  [  — f  I  (  —  ]  file  •••  directory  directory 

DESCRIPTION 

Mv  moves  files  and  directories  around  in  the  file  system.  A  side  effect  of  mv  is  to  rename  a  file  or 
directory.  The  three  major  forms  of  mv  are  shown  in  the  synopsis  above. 

The  first  form  of  mv  moves  (changes  the  name  of)  file!  to  file2.  If  file2  already  exists,  it  is 
removed  before  Jilel  is  moved.  If  fiU2  has  a  mode  which  forbids  writing,  mi;  prints  the  mode 
(see  chmod{2))  and  reads  the  standard  input  to  obtain  a  line;  if  the  line  begins  with  y,  the  move 
takes  place,  otherwise  mt;  exits. 

The  second  form  of  mv  moves  (changes  the  name  of)  directory  1  to  directory2y  ONLY  if  direc- 
tory2  does  not  already  exist  —  if  it  does,  the  third  form  applies. 

The  third  form  of  mi;  moves  one  or  more  files  and  directories,  with  their  original  names,  to  the 
last  directory  in  the  list. 

Mv  refuses  to  move  a  file  or  directory  onto  itself. 

OPTIONS 


-f 


SEE  ALSO 

cp(l),  In(l) 

BUGS 

If  filel  and  file2  are  on  different  file  systems,  then  mv  must  copy  the  file  and  delete  the  original. 
In  this  case  the  owner  name  becomes  that  of  the  copying  process  and  any  linking  relationship 
with  other  files  is  lost. 

Mv  will  not  move  a  directory  from  one  file  system  to  another. 


interactive  mode:  mv  displays  the  name  of  the  file  or  directory  followed  by  a  question 
mark  whenever  a  move  would  replace  an  existing  file  or  directory.  If  you  type  a  line 
starting  with  ^y’,  mv  moves  the  specified  file  or  directory,  otherwise  mi;  does  nothing  with 
that  file  or  directory. 

force:  override  any  mode  restrictions  and  the  —I  switch.  The  — f  option  also  suppresses 
any  warning  messages  about  modes  which  would  potentially  restrict  overwriting. 

Interpret  all  the  following  arguments  to  mi;  as  file  names.  This  allows  file  names  starting 
with  minus. 
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NAME 

nm  -  print  name  list 
SYNOPSIS 

nm  [  — gnoprua  |  [  file  •••  | 

DESCRIPTION 

Nm  prints  the  name  list  (symbol  table)  of  each  object  file  in  the  argument  list.  If  an  argument  is 
an  archive,  a  listing  for  each  object  file  in  the  archive  will  be  produced.  If  no  file  is  given,  the 
symbols  in  a, out  are  listed. 

Each  symbol  name  is  preceded  by  its  value  (blanks  if  undefined)  and  one  of  the  letters: 

U  (undefined), 

A  (absolute), 

T  (text  segment  symbol), 

D  (data  segment  symbol), 

B  (bss  segment  symbol), 

C  (common  symbol), 

f  file  name, 

—  debug  symbol  table  entries  (see  —a  below). 

If  the  symbol  is  local  (non-external)  the  type  letter  is  in  lower  case.  The  output  is  sorted  alpha¬ 
betically. 

OPTIONS 

“g  Print  only  global  (external)  symbols. 

— n  Sort  numerically  rather  than  alphabetically. 

— o  Prepend  file  or  archive  element  name  to  each  output  line  rather  than  only  once. 

— p  Don’t  sort;  print  in  symbol-table  order. 

— r  Sort  in  reverse  order. 

— u  Print  only  undefined  symbols. 

—a  Print  all  symbols. 

EXAMPLE 

nm 

prints  the  symbol  list  of  a, out,  the  default  output  file  for  the  C  compiler^ 

SEE  ALSO 

ar(l),  ar(5),  a.out(5) 
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NAME 

nroff  —  text  formatting  and  typesetting 
SYNOPSIS 

nroff  I  —opagelist  |  (  — niV]  [  — liV)  [  —mnatne  [  [  — raNj  [  — 1 1  [  — q  |  (  — Tname  | 

(  — €  I  [  — h  I  [  file  ] 

DESCRIPTION 

formats  text  in  the  named  files  for  typewriter-like  devices.  See  also  troff{l).  The  full  capa¬ 
bilities  of  nroff  and  troff  are  described  in  Formatting  Documents  with  Nroff  and  Troff, 

If  no  file  argument  is  present,  nroff  reads  the  standard  input.  An  argument  consisting  of  a  single 
minus  (— )  is  taken  to  be  a  file  name  corresponding  to  the  standard  input. 

OPTIONS 

Options  may  appear  in  any  order  so  long  as  they  appear  before  the  files. 

— ofisf  Print  only  pages  whose  page  numbers  appear  in  the  comma-separated  list  of  numbers 
and  ranges.  A  range  N—M  means  pages  N  through  Af;  an  initial  — iV  means  from  the 
beginning  to  page  N;  and  a  final  N—  means  from  TV  to  the  end. 

— nTV  Number  first  generated  page  TV. 

— bTV  Stop  every  TV  pages.  Nroff  will  halt  prior  to  every  TV  pages  (default  TV=1)  to  allow  paper 

loading  or  changing,  and  will  resume  upon  receipt  of  a  newline. 

—mname 

Prepend  the  macro  file  /usr/llb/tmae/tmae.name  to  the  input  files. 

— raTV  Set  register  a  (one-character)  to  TV. 

*^1  Read  standard  input  after  the  input  files  are  exhausted. 

— q  Invoke  the  simultaneous  input-output  mode  of  the  rd  request. 

— Tname 

Prepare  output  for  a  device  of  the  specified  name.  Known  names  are: 

37  Teletype  Corporation  Model  37  terminal  —  this  is  the  default. 

tn300  GE  TermiNet  300  (or  any  terminal  without  half-line  capability), 

300S  DASI-300S 

300  DASI-300 

300X  DASI-300X 

450  DASI-450  (Diablo  Hyterm). 

450-12  DASI-450  (Diablo  Hyterm)  —  12-pitch. 

450-12-8  DASI-450  (Diablo  Hyterm)  —  12-pitch  and  8  lines-per-inch. 

450X  DASI-450X  (Diablo  Hyterm). 

Ipr  Line  printer. 

xl700  Xerox  1700  daisywheel  printer, 

— e  Produce  equally-spaced  words  in  adjusted  lines,  using  full  terminal  resolution. 

—h  Use  output  tabs  during  horizontal  spacing  to  speed  output  and  reduce  output  character 
count.  Tab  settings  are  assumed  to  be  every  8  nominal  character  widths. 

EXAMPLE 

gaia%  nroff  — s4  —me  users.guide 

Formats  users^guide  using  the  —me  macro  package,  and  stopping  every  4  pages. 

FILES 

/tmp/ta*  temporary  file 

/usr/lib/tmac/tmac.*  standard  macro  files 
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/usr/Hb/term/*  terminal  driving  tables  for  nroff 

SEE  ALSO 

Formatting  Documents  with  Nroff  and  Troff  in  Editing  and  Text  Processing  on  the  Sun  Worksta¬ 
tion. 

troff(l),  eqn(l),  tbl(l),  ms(7),  me(7),  man(7),  col(l),  checknr(l) 
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NAME 

od  —  octal,  decimal,  hex,  ascii  dump 
SYNOPSIS 

od  I  —format  ]  |  file  ]  |  [+|offset|.]|b|  [label]  | 

DESCRIPTION 

Od  displays  file,  or  it’s  standard  input,  in  one  or  more  dump  formats  as  selected  by  the  first 
argument.  If  the  first  argument  is  missing,  — o  (octal)  is  the  default.  J)umping  continues  until 
end-of-file. 

The  meanings  of  the  format  argument  characters  are: 

a  Interpret  bytes  as  characters  and  display  them  vfith  their  ASCII  names.  If  the  p  character 
is  given  also,  bytes  with  even  parity  are  underlined.  If  the  P  character  is  given,  bytes  with 
odd  parity  are  underlined.  Otherwise  the  parity  bit  is  ignored. 

b  Interpret  bytes  as  unsigned  octal. 

c  Interpret  bytes  as  ASCII  characters.  Certain  non-graphic  characters  appear  as  C  escapes: 
null=\0,  backspace=\b,  formfeed*=\f,  newline=\n,  return=\r,  tab=\t;  others  appear  as  3- 
digit  octal  numbers.  Bytes  with  the  parity  bit  set  are  displayed  in  octal. 

d  Interpret  (short)  words  as  unsigned  decimal, 
f  Interpret  long  words  as  fioating  point, 
h  Interpret  (short)  words  as  unsigned  hexadecimal. 

I  Interpret  (short)  words  as  signed  decimal. 

1  Interpret  long  words  as  signed  decimal, 
o  Interpret  (short)  words  as  unsigned  octal. 

ejn]  Look  for  strings  of  ASCII  graphic  characters,  terminated  with  a  null  byte.  N  specifies  the 
minimum  length  string  to  be  recognized.  By  default,  the  minimum  length  is  3  characters. 

V  Show  all  data.  By  default,  display  lines  that  are  identical  to  the  last  line  shown  are  not  out¬ 
put,  but  are  indicated  with  an  in  column  1. 

wjnj  Specifies  the  number  of  input  bytes  to  be  interpreted  and  displayed  on  each  output  line.  If 
w  is  not  specified,  16  bytes  are  read  for  each  display  line.  If  n  is  not  specified,  it  defaults  to 
32. 

X  Interpret  (short)  words  as  hexadecimal. 

An  upper  case  format  character  implies  the  long  or  double  precision  form  of  the  object. 

The  ofi^eel  argument  specifies  the  byte  offset  into  the  file  where  dumping  is  to  commence.  By 
default  this  argument  is  interpreted  in  octal.  A  different  radix  can  be  specified;  If  is 
appended  to  the  argument,  then  offset  is  interpreted  in  decimal.  If  offset  begins  with  “x”  or 
“Ox”,  it  is  interpreted  in  hexadecimal.  If  “b”  (“B”)  is  appended,  the  offset  is  interpreted  as  a 
block  count,  where  a  block  is  512  (1024)  bytes.  If  the  file  argument  is  omitted,  an  offset  argu¬ 
ment  must  be  preceded  by 

The  radix  of  the  displayed  address  will  be  the  same  as  the  radix  of  the  offset,  if  specified;  other¬ 
wise  it  will  be  octal. 

Label  will  be  interpreted  as  a  pseudo-address  for  the  first  byte  displayed.  It  will  be  shown  in  “()” 
following  the  file  offset.  It  is  intended  to  be  used  with  core  images  to  indicate  the  real  memory 
address.  The  syntax  for  label  is  identical  to  that  for  offset. 

SEE  ALSO 

adb(l) 
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BUGS 

A  file  name  argument  can’t  start  with  A  hexadecimal  offset  can’t  be  a  block  count.  Only 

one  file  name  argument  can  be  given. 

It  is  an  historical  botch  to  require  specification  of  object,  radix,  and  sign  representation  in  a  sin¬ 
gle  character  argument. 
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NAME 

pagesize  —  print  system  page  size 

SYNOPSIS 

pagesise 

DESCRIPTION 

Pagesize  prints  the  size  of  a  page  of  memory  in  bytes,  as  returned  by  g€tpage$ize{2).  This  pro¬ 
gram  is  useful  in  constructing  portable  shell  scripts* 

SEE  ALSO 

getpagesize(2) 
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NAME 

passwd  —  change  login  password 
SYNOPSIS 

pasflwd  (  —f  jilename  |  [  ustr~lD  \ 

DESCRIPTION 

This  command  changes  (or  installs)  a  password  associated  with  the  udtr-ID  (your  own  by 
default). 

Pasmd  prompts  for  the  old  password  and  then  for  the  new  one.  You  must  supply  both,  and  the 
new  password  must  be  typed  twice  to  forestall  mistakes. 

New  passwords  must  be  at  least  four  characters  long,  if  they  use  a  sufficiently  rich  alphabet,  or 
at  least  six  characters  long  if  in  monocase. 

Only  the  owner  of  the  name  or  the  super-user  may  change  a  password;  the  owner  must  prove  he 
knows  the  old  password. 

OPTIONS 

— f  Treat  file  as  the  password  file. 

FILES 

/etc/passwd 

/etc/yp/passwd 

SEE  ALSO 

login(l),  passwd(5),  crypt(3),  yppasswd(l) 

Robert  Morris  and  Ken  Thompson,  UNIX  Pa9Bword  Security 

BUGS 

Passwd  will  not  change  your  password  if  your  system  uses  the  yp  Yellow  Pages  name  server. 
Refer  to  for  more  information. 
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NAME 

pc  —  Pascal  compiler 
SYNOPSIS 

pc  I  -c  ]  j  — g  ]  [  — o  output  ]  I  -O  I  [  -b  I  I  — C  ]  [  — fsky  |  ]  -H  ]  [  -1  name  . . .  [  [  — I  j 

I  — Ipfc  I  [  — L  ]  I  — P  ]  [  — 8  I  [  — S  j  f  — *  ]  filename.p  . . . 

DESCRIPTION 

Pc  is  the  Sun  Pascal  compiler.  If  given  an  argument  file  ending  with  *p,  pc  compiles  the  file  and 
leaves  the  result  in  an  executable  file  called  a*out  by  default, 

A  program  may  be  separated  into  more  than  one  mp  file.  Pc  will  compile  a  number  of  .p  files  into 
object  files  (with  the  extension  .0  in  place  of  .p).  Object  files  may  then  be  loaded  into  an  execut¬ 
able  a^oui  file.  Exactly  one  object  file  must  supply  a  program  statement  to  successfully  create 
an  executable  a^out  file.  The  rest  of  the  files  must  consist  only  of  declarations  which  logically 
nest  within  the  program.  References  to  objects  shared  between  separately  compiled  files  are 
allowed  if  the  objects  are  declared  in  Included  header  files,  whose  names  must  end  with  .k. 
Header  files  may  only  be  included  at  the  outermost  level,  and  thus  declare  only  globally  available 
objects.  To  allow  external  functions  and  procedures  to  be  declared,  an  external  directive  has 
been  added,  whose  use  is  similar  to  the  forward  directive  but  restricted  to  appear  only  in  *h 
files.  Function  and  procedure  bodies  may  not  appear  in  •A  files,  A  binding  phase  of  the  com¬ 
piler  checks  that  declarations  are  used  consistently,  to  enforce  the  type  checking  rules  of  Pascal. 

Object  files  created  by  other  language  processors  may  be  loaded  together  with  object  files  created 
by  pc.  The  functions  and  procedures  they  define  must  have  been  declared  in  .A  files  included 
by  all  the  •p  files  which  call  those  routines, 

Pascal’s  calling  conventions  are  the  same  as  in  C,  with  var  parameters  passed  by  address  and 
other  parameters  passed  by  value. 

Both  pc  and  pt(l)  support  ISO  Level  1  Standard  Pascal,  including  conformant  array  parameters. 
Deviations  from  the  ISO  Standard  are  noted  under  BUGS  below. 

See  the  Pascal  User's  Manual  for  details. 

OPTIONS 

See  id{l)  for  load-time  options. 

— c  Suppress  loading  and  produce  *0  file(s)  from  source  file(s). 

— g  Produce  additional  symbol  table  information  for  the  symbolic  debugger  dbx{l). 

— o  name 

Name  the  final  output  file  name  instead  of  a, out 
— O  Optimize  the  object  code. 

— b  Buffer  the  file  output  in  units  of  disk  blocks,  rather  than  lines. 

— C  Compile  code  to  perform  subscript  and  subrange  checks,  verify  assert  statements,  and 

initialize  all  variables  to  zero  as  in  pi.  Note  that  pointers  are  not  checked.  This  option 
differs  significantly  from  the  -C  option  of  the  cc  compiler, 

— fsky  Generate  code  which  assumes  the  presence  of  a  SKY  floating-point  processor  board.  Pro¬ 
grams  compiled  with  this  option  can  only  be  run  in  systems  that  have  a  SKY  board 
installed.  Programs  compiled  without  the  —fsky  option  will  use  the  SKY  board  from 
library  routines,  but  won’t  run  as  fast  as  they  would  if  the  — feky  option  were  used.  If 
any  part  of  a  program  is  compiled  using  the  —fsky  option,  you  must  also  use  this  option 
when  linking  with  the  pc  command,  since  different  startup  routines  are  used  to  initialize 
the  SKY  board. 

— H  Compile  code  to  perform  range  checks  on  pointers  into  the  heap. 

—I  name 
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Produce  a  listing  for  the  specified  procedures,  functions  and  include  files. 

—1  Make  a  program  listing  during  translation* 

— Ipfc  Load  common  startup  code  for  programs  containing  mixed  Pascal  and  FORTRAN  object 
files.  Such  programs  should  also  be  loaded  with  the  FORTRAN  libraries  (see  flies  below). 

— L  Map  upper  case  letters  in  keywords  and  identifiers  to  lower  case. 

— P  Use  partial  evaluation  semantics  for  the  boolean  operators  and  and  or.  For  these  opera¬ 

tors  only,  left-to-right  evaluation  is  guaranteed,  and  the  second  operand  is  evaluated  only 
if  necessary  to  determine  the  result. 

•^8  Accept  standard  Pascal  only;  nonstandard  constructs  cause  warning  diagnostics. 

— S  Compile  the  named  program,  and  leave  the  assembly  language  output  on  the  correspond¬ 

ing  file  suffixed  ‘.s\  No  ‘.o’  is  created. 

—z  Allow  execution  profiling  with  pxp  by  generating  statement  counters,  and  arranging  for 
the  creation  of  the  profile  data  file  pmon^out  when  the  resulting  object  is  executed. 

Other  arguments  are  taken  to  be  loader  option  arguments  or  libraries  of  pc  compatible  routines. 
Certain  flags  can  also  be  controlled  in  comments  within  the  program,  as  described  in  the  Pascal 
User's  Manual  in  the  Sun  Pascal  Manual. 

FILES 

file.p 
/lib/cpp 
/usr/lib/pcO 
/lib/fl 
/usr/lib/pc2 
/lib/c2 
/usr/lib/pc3 
/usr/lib/pc3,2strings 
/usr/lib/how_pc 
/usr/Iib/libpc.a 
/usr/lib/libpfc.a 
grams 

/usr/lib/libF77.a 
/usr/lib/libI77.a 
/usr/lib/libU77.a 
/usr/lib/libm.a 
/lib/libc,a 

SEE  ALSO 

The  Pascal  User's  Manual  in  the  Sun  Pascal  Manual. 
pi(l),  pxp(l),  pxrer(l) 

DIAGNOSTICS 

For  a  basic  explanation  do 
tutoriaI%  pc 

In  the  diagnostic  output  of  the  translator,  lines  containing  syntax  errors  are  listed  with  a  flag 
indicating  the  point  of  error.  Diagnostic  messages  indicate  the  action  which  the  recovery 
mechanism  took  in  order  to  be  able  to  continue  parsing.  Some  diagnostics  indicate  only  that  the 
input  is  ‘malformed.’  This  occurs  if  the  recovery  can  find  no  simple  correction  to  make  the  input 
syntactically  valid. 

Semantic  error  diagnostics  indicate  a  line  in  the  source  text  near  the  point  of  error.  Some  errors 
evoke  more  than  one  diagnostic  to  help  pinpoint  the  error;  the  follow-up  messages  begin  with  an 
ellipsis 


Pascal  source  files 
macro  preprocessor 
compiler 
code  generator 

inline  expander  of  library  calls 
peephole  optimizer 

separate  compilation  consistency  checker 

text  of  the  error  messages 

basic  usage  explanation 

intrinsic  functions  and  I/O  library 

startup  code  for  combined  Pascal  and  FORTRAN  pro- 

FORTRAN  intrinsics  library 
FORTRAN  I/O  library 
FORTRAN<=^>Unix  interface  library 
math  library 

standard  library,  see  in^r£>(3) 
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The  first  character  of  each  error  message  indicates  its  class: 

E  Fatal  error;  no  code  will  be  generated, 

e  Nonfatal  error, 

w  Warning  —  a  potential  problem, 

s  Nonstandard  Pascal  construct  warning. 

If  a  severe  error  occurs  which  inhibits  further  processing,  the  translator  will  give  a  diagnostic  and 
then  ‘QUir. 

Names  whose  definitions  conflict  with  library  definitions  draw  a  warning.  The  library  definition 
will  be  replaced  by  the  one  supplied  in  the  Pascal  program.  Note  that  this  can  have  unpleasant 
sideeffects. 

BUGS 

The  keyword  packed  is  recognized  but  has  no  effect.  The  ISO  standard  requires  packed  and 
unpacked  structures  to  be  distinguished  for  portability  reasons. 

Binary  set  operators  are  required  to  have  operands  with  identical  types;  the  ISO  standard  allows 
different  types,  as  long  as  the  underlying  base  types  are  compatible. 

The  flag  doesn’t  work  for  separately  compiled  files. 

Because  the  «  option  is  usurped  by  the  compiler,  it  is  not  possible  to  pass  the  strip  option  to  the 
loader.  Thus  programs  which  are  to  be  stripped,  must  be  run  through  after  they  are 

compiled. 
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NAME 

perfmeter  —  meter  display  of  system  performance  values 
SYNOPSIS 

perfmeter  [  — b  sampletime  ]  \  — h  hourkandintv  ]  [  —m  minutekandintv  j  [  — v  value  ] 

I  hostname  ] 

DESCRIPTION 

Perfmeter  starts  a  tool  whose  iconic  form  is  a  meter  displaying  a  system  performance  value,  and 
whose  open  form  is  a  strip  chart  of  that  value.  The  default  is  for  the  meter  to  be  updated  with  a 
sampletime  of  2  seconds,  for  the  hour  hand  to  represent  an  average  over  an  interval  of  20 
seconds,  for  the  minute  hand  to  represent  an  average  over  2  seconds,  and  for  the  value  being 
displayed  to  be  percent  of  cpu  being  utilized.  These  defaults  can  be  modified  with  command  line 
arguments,  or  dynamically  after  the  tool  has  been  started.  If  there  is  no  hostname  argument, 
then  the  data  displayed  will  be  for  the  local  machine,  otherwise  for  the  machine  named  by  host- 
name,  In  either  case,  the  rstatd(8)  daemon  must  be  running  on  the  machine  for  which  statistics 
are  being  reported. 

OPTIONS 

—8  eampletime 

Sets  the  sample  time  to  sampletime  seconds. 

— h  hourhandintv 

Sets  the  hour  hand  interval  to  hourhandintv  seconds. 


— m  minutehandintv 

Sets  the  minute  hand  interval  to  minutehandintv  seconds, 
— V  value 

Set  the  performance  value  to  be  monitored  to  one  of: 

cpu  percent  of  cpu  being  utilized 

pkts  ethernet  packets  per  second 

page  paging  activity  in  pages  per  second 

swap  jobs  swapped  per  second 

disk  disk  traffic  in  transfers  per  second 

Intr  number  of  device  interrupts  per  second 

cntxt  number  of  context  switches  per  second 


COMMANDS 

The  value  being  displayed  can  be  changed  by  clicking  the  tool  with  the  rightmost  mouse  button, 
and  then  selecting  the  appropriate  menu  item.  The  other  meter  parameters  can  be  modified  by 
moving  the  mouse  cursor  into  the  tool  (either  open  or  closed),  and  typing: 

m  decreases  minutekandintv  by  one 

M  increases  minutehandintv  by  one 

b  decreases  hourhandintv  by  one 

H  increases  hourhandintv  by  one 

1-9  Sets  sampletime  to  a  range  from  1  to  9  seconds. 


FILES 

/etc/servers 


starts  statistics  server 


SEE  ALSO 

perfmon(l),  netstat(8),  vmstat(8),  suntools(l),  rstatd(8) 
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NAME 

perfmon  —  graphical  display  of  general  system  statistics 
SYNOPSIS 

perfmon  [  statistic  • « •  ] 

DESCRIPTION 

Perfmon  provides  a  graphical  display  of  the  system-wide  performance  statistics  and  updates  them 
approximately  once  a  second.  It  should  be  executed  from  a  graphics  tool  inside  the  SunWindows 
system.  The  time  interval  between  updates  can  be  adjusted  by  typing  one  of  the  following  char¬ 
acters  while  the  mouse  is  in  the  graphics  subwindow: 

8  increases  the  interval  by  0.05  seconds  (small  a  means  get  slower  by  a  little). 

S  increases  the  interval  by  one  second  (capital  S  means  get  51ower  by  a  lot), 

f  decreases  the  interval  by  0,05  seconds  (small  /  means  get  /aster  by  a  little). 

F  decreases  the  interval  by  one  second  (capital  F  means  get  Faster  by  a  lot). 

R  resets  the  interval  to  the  standard  1,05  seconds. 

In  addition,  typing: 

H,  h  or  r 

lists  the  characters  that  perfmon  is  listening  for. 

Q  or  q  causes  perfmon  to  cease  executing. 

If  no  statistic  argument  is  given,  perfmon  displays  all  statistics.  A  tick  is  placed  on  the  lines 
separating  the  graphs  once  every  fifteen  seconds  (due  to  scheduling  vagaries,  these  ticks  may  not 
be  evenly  spaced). 

Statistics 

user  is  the  percentage  of  total  CPU  time  spent  in  normal  and  low  priority  user  processes, 

system 

is  the  percentage  of  total  CPU  time  attributed  to  system  calls  and  overhead, 
idle  is  the  percentage  of  total  CPU  time  spent  idle, 
free  is  the  amount  of  available  real  memory  (in  Kbytes), 
disk  is  the  total  number  of  disk  transfers  performed. 

interrupts 

is  the  total  number  of  interrupts  serviced, 
input  is  the  total  number  of  input  packets  received. 

output 

is  the  total  number  of  output  packets  transmitted. 

collision 

is  the  total  number  of  collisions  between  packets  observed  on  the  network. 


SEE  ALSO 

netstat(8),  perfmeter(l),  suntools(l),  vmstat(8) 

BUGS 

Perfmon  should  use  rataid. 
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NAME 

pi  -  Pascal  interpreter  code  translator 
SYNOPSIS 

pi  1  -b  1  (  -i  ]  I  -L  1  [  -n  ]  I  -o  name  1  [  -P  1  1  -•  |  (  -t  ]  |  -u  [  |  ~w  |  (  -■  ] 

[  —I  name  • . .  |  name.p 

DESCRIPTION 

Pi  translates  the  program  in  the  file  name.p  leaving  interpreter  code  in  the  file  obj  in  the  current 
directory.  The  interpreter  code  can  be  executed  using  px.  Piz  performs  the  functions  of  pi  and 
pz  for  ‘load  and  go’  Pascal. 

Both  pi  and  pc(l)  support  ISO  Level  1  Standard  Pascal,  including  conformant  array  parameters. 
Deviations  from  the  ISO  Standard  are  noted  under  BUGS  below. 

OPTIONS 

The  following  flags  are  interpreted  by  pi;  the  associated  options  can  also  be  controlled  in  com¬ 
ments  within  the  program;  see  the  Pascal  User's  Manual  in  the  Sun  Fortran  and  Pascal 
Manual  for  details. 

— b  Buffer  the  file  output  in  units  of  disk  blocks,  rather  than  lines. 

— !  name 

Enable  the  listing  for  any  specified  procedures,  functions,  and  Include  files. 

—1  Make  a  program  listing  during  translation. 

— L  Map  all  identifiers  and  keywords  to  lower  case. 

— n  Begin  each  listed  include  file  on  a  new  page  with  a  banner  line. 

— o  name 

Name  the  final  output  file  name  instead  of  a,ouL 

— p  Suppress  the  post-mortem  control  flow  backtrace  if  an  error  occurs;  suppress  statement 

limit  counting. 

—8  Accept  standard  Pascal  only;  non-standard  constructs  cause  warning  diagnostics. 

— t  Suppress  runtime  tests  of  subrange  variables  and  treat  assert  statements  as  comments. 

— u  Card  image  mode;  only  the  first  72  characters  of  input  lines  are  used. 

— w  Suppress  warning  diagnostics. 

—t  Allow  execution  profiling  with  pxp  by  generating  statement  counters,  and  arranging  for  the 
creation  of  the  profile  data  file  pmon.out  when  the  resulting  object  is  executed. 

FILES 

file.p  input  file 

file.i  include  file(s) 

/usr/lib/pi3,*5trings  text  of  the  error  messages 

/usr/lib/how„pi*  basic  usage  explanation 

obj  interpreter  code  output 

SEE  ALSO 

Sun  Fortran  and  Pascal  Manual 
pix(l),  px(l),  pxp(l),  pxref(l) 

DIAGNOSTICS 

For  a  basic  explanation  do 
tutorial%  pi 

In  the  diagnostic  output  of  the  translator,  lines  containing  syntax  errors  are  listed  with  a  flag 
indicating  the  point  of  error.  Diagnostic  messages  indicate  the  action  which  the  recovery 
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mechanism  took  in  order  to  be  able  to  continue  parsing.  Some  diagnostics  indicate  only  that  the 
input  is  ‘malformed.’  This  occurs  if  the  recovery  can  find  no  simple  correction  to  make  the  input 
syntactically  valid. 

Semantic  error  diagnostics  indicate  a  line  in  the  source  text  near  the  point  of  error.  Some  errors 
evoke  more  than  one  diagnostic  to  help  pinpoint  the  error;  the  follow-up  messages  begin  with  an 
ellipsis 

The  first  character  of  each  error  message  indicates  its  class: 

E  Fatal  error;  no  code  will  be  generated, 

e  Non-fata!  error, 

w  Warning  —  a  potential  problem, 

s  Non-standard  Pascal  construct  warning. 

If  a  severe  error  occurs  which  inhibits  further  processing,  the  translator  will  give  a  diagnostic  and 
then  ‘QUIT’. 

BUGS 

The  keyword  packed  is  recognized  but  has  no  effect.  The  ISO  standard  requires  packed  and 
unpacked  structures  to  be  distinguished  for  portability  reasons. 

Binary  set  operators  are  required  to  have  operands  with  identical  types;  the  ISO  standard  allows 
different  types,  as  long  as  the  underlying  base  types  are  compatible. 

For  clarity,  semantic  errors  should  be  flagged  at  an  appropriate  place  in  the  source  text,  and 
multiple  instances  of  the  ‘same’  semantic  error  should  be  summarized  at  the  end  of  a  procedure 
or  function  rather  than  evoking  many  diagnostics. 

When  include  files  are  present,  diagnostics  relating  to  the  last  procedure  in  one  file  may  appear 
after  the  beginning  of  the  listing  of  the  next. 
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NAME 

pix  —  Pascal  translator  and  interpreter 
SYNOPSIS 

plx]  options  I  [  — i  name  ...  ]  name.p  (  argument ...  j 
DESCRIPTION 

Pix  is  a  ‘load  and  go'  version  of  Pascal  which  combines  the  functions  of  the  translator  p*  and  the 
interpreter  pz.  Pix  uses  pi  to  translate  the  program  in  the  file  name.p  and,  if  there  were  no  fatal 
errors  during  translation,  calls  px  to  execute  the  resulting  interpretive  code  with  the  specified 
arguments.  A  temporary  file  is  used  for  the  object  code;  the  file  obj  is  neither  created  nor  des¬ 
troyed. 

Options  are  as  described  under  pi(l). 

FILES 

/usr/ucb/pi  Pascal  translator 

/usr/ucb/px  Pascal  interpreter 

/tmp/pix*  temporary 

/usr/lib/how_pix  basic  explanation 

SEE  ALSO 

The  Pascal  User’s  Manual  in  the  Pascal  for  the  Sun  Workstation  Manual. 
pi(l),  px(l) 

DIAGNOSTICS 

For  a  basic  explanation  do 
tutorial%  pbt 
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NAME 

plot  —  graphics  filters 
SYNOPSIS 

plot  [  — Tterminal  [  raster  |  ] 

DESCRIPTION 

These  commands  read  plotting  instructions  (see  plot{5))  from  the  standard  input,  and  in  general 
produce  plotting  instructions  suitable  for  a  particular  terminal  on  the  standard  output. 

If  no  terminal  type  is  specified,  the  environment  parameter  TERM  (sec  ent;iran(5))  is  used. 
Known  terminals  are: 

4014  Tektronix  4014  storage  scope, 

450  DASI  Hyterm  450  terminal  (Diablo  mechanism). 

300  DASI  300  or  GSI  terminal  (Diablo  mechanism). 

300S  DASI  300S  terminal  (Diablo  mechanism). 

ver  Versatec  D1200A  printer-plotter.  This  version  of  plot  places  a  scan-converted  image  in 
jnsr/lmpf  raster  and  sends  the  result  directly  to  the  plotter  device  rather  than  to  the 
standard  output.  The  optional  argument  sends  a  previously  scan-converted  file  called 
raster  to  the  plotter. 

FILES 

/usr/bin/tek 

/usr/bin/t450 

/usr/bin/t300 

/usr/bin/t300s 

/usr/bin/vplot 

/usr/tmp/raster 

SEE  ALSO 

plot(3X),  plot(5) 

BUGS 

There  is  no  lockout  protection  for  fusrf  imp f  raster. 
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NAME 

pmerge  —  pascal  file  merger 

SYNOPSIS 

pmerge  name.p  ... 

DESCRIPTION 

Pmerge  assembles  the  named  Pascal  files  into  a  single  standard  Pascal  program.  The  resulting 
program  is  listed  on  the  standard  output.  It  is  intended  to  be  used  to  merge  a  collection  of 
separately  compiled  modules  so  that  they  can  be  run  through  pi,  or  exported  to  other  sites. 

FILES 

/usr/tmp/MG*  default  temporary  files 

SEE  ALSO 

pc(l),  pi(l), 

Auxiliary  documentation  Pascal  User's  Manual  in  the  Sun  Fortran  and  Pascal  Manual. 

BUGS 

Very  minimal  error  checking  is  done,  so  incorrect  programs  will  produce  unpredictable  results. 
Block  comments  should  be  placed  after  the  keyword  to  which  they  refer  or  they  are  likely  to  end 
up  in  bizarre  places. 
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NAME 

postnews  —  submit  news  articles 

SYNOPSIS 

postnews  j  article  | 

DESCRIPTION 

Postnewa  calls  up  the  mciy^(l)  utility  to  submit  news  articles  to  USENET.  Postnews  prompts  you 
for  the  title  of  the  article,  for  the  newsgroup,  and  for  the  distribution.  The  title  of  the  article 
should  be  a  phrase  suggesting  the  subject,  so  that  persons  reading  the  news  can  tell  if  they  are 
interested  in  the  article. 

If  you  omit  the  name  of  the  newsgroup  (by  typing  a  carriage-return  when  asked  for  the  news- 
group),  postnews  posts  the  article  to  general. 

general  is  read  by  everyone  on  the  local  machine.  Other  possible  newsgroups  include,  but  are  not 
limited  to,  btl. general,  read  by  all  users  at  all  Bell  Labs  sites  on  USENET,  net. general,  read  by 
all  users  at  all  sites  on  USENET,  and  net. news,  read  by  users  interested  in  the  network  news  on 
ail  sites.  There  is  often  a  local  set  of  newsgroups,  such  as  ucb.ali,  that  circulate  within  a  local 
set  of  machines.  In  this  case,  ucb  newsgroups  circulate  among  machines  at  the  University  of  Cali¬ 
fornia  at  Berkeley. 

The  distribution  can  be  any  valid  list  of  newsgroup  names,  and  defaults  to  the  same  as  the  news- 
group.  If  they  are  the  same,  the  distribution  is  omitted  from  the  headers  put  into  the  editor 
buffer.  A  distribution  header  is  included  in  the  headers  of  the  article  if  given,  affecting  where  the 
article  is  distributed  to. 

After  entering  the  title,  newsgroup,  and  distribution,  postnews  calls  up  an  editor  program  where 
you  can  compose  the  article.  Postnews  uses  vi(l)  as  the  editor  unless  you  have  specified  another 
editor  via  the  SEDITOR  environment  variable,  in  which  case  postnews  uses  the  editor  specified 
there. 

An  initial  set  of  headers  containing  the  subject  and  newsgroups  will  be  placed  in  the  editor,  fol¬ 
lowed  by  a  blank  line.  The  article  should  be  appended  to  the  buffer,  after  the  blank  line.  These 
headers  can  be  changed,  or  additional  headers  added,  while  in  the  editor,  if  desired. 

Optionally,  the  article  is  read  from  the  file  specified  by  article. 

For  more  sophisticated  uses,  such  as  posting  news  from  a  program,  see  meu;5(l). 

SEE  ALSO 

mail(l),  checknews(l),  inews(l),  readnews(l). 
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NAME 

pr  —  print  file(s),  possibly  in  multiple  columns 

SYNOPSIS 

pr  [  -n  ]  [  -pn  j  [  -h  string  |  [  -wn  ]  [  --f  I  |  —In  |  [  -t  |  |  — sn  ]  (  — m  ]  [  file  j  . . . 

DESCRIPTION 

Pr  prepares  one  or  more  files's  for  printing.  The  output  is  separated  into  pages  headed  by  a 
date,  the  name  of  the  file  or  a  specified  header,  and  the  page  number.  Pr  prints  its  standard 
input  if  there  are  no  file  arguments. 

Inter-terminal  messages  via  u;rt7e(l)  are  forbidden  during  a  pr, 

OPTIONS 

Options  apply  to  alt  following  filers  but  may  be  reset  between  file's: 

— n  Produce  n-column  output.  This  option  overrides  the  — t  option  (see  below). 

-l-n  Begin  printing  with  page  n. 

— h  string 

Use  string  as  a  header  for  the  page  instead  of  the  default  header. 

— wn  For  purposes  of  multi-column  output,  take  the  width  of  the  page  to  be  n  characters 
instead  of  the  default  72. 

—f  Use  formfeeds  instead  of  newlines  to  separate  pages.  A  formfeed  is  assumed  to  use  up 
two  blank  lines  at  the  top  of  a  page.  Thus  this  option  does  not  affect  the  effective  page 
length. 

—In  Take  the  length  of  the  page  to  be  n  lines  instead  of  the  default  66. 

— t  Do  not  print  the  5-line  header  or  the  5-line  trailer  normally  supplied  for  each  page. 

Formfeed  characters  are  not  generated  when  this  option  is  used,  even  if  the  — f  option 
was  used.  The  — t  option  is  intended  for  applications  where  the  results  should  be 
directed  to  a  file  for  further  processing. 

—Bc  Separate  columns  by  the  single  character  c  instead  of  by  the  appropriate  amount  of 
white  space.  A  missing  c  is  taken  to  be  a  tab. 

— m  Print  all  file's  simultaneously,  each  in  one  column, 

EXAMPLES 

Print  a  file  called  dreadnaugkt  on  the  printer  —  this  is  the  simplest  use  of  pr: 
krypton%  pr  dreadnaught  |  Ipr 
krypton% 

Produce  three  laminations  of  a  file  called  ridings  side  by  side  in  the  output,  with  no  headers  or 
trailers,  the  results  to  appear  in  the  file  called  Yorkshire: 

krypton%  pr  — m  — t  ridings  ridings  ridings  >  Yorkshire 
krypton% 

FILES 

/dev/tty?  to  suspend  messages, 

SEE  ALSO 

cat(l),  Ipr(l) 

DUGNOSTICS 

There  are  no  diagnostics  when  pr  is  printing  on  a  terminal. 

BUGS 

The  options  described  above  interact  with  each  other  in  strange  and  as  yet  to  be  defined  ways. 
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NAME 

printenv  —  print  out  the  environment 

SYNOPSIS 

printenv  |  name  | 

DESCRIPTION 

Printenv  prints  out  the  values  of  the  variables  in  the  environment.  If  a  name  is  specified,  only  its 
value  is  printed. 

If  a  name  is  specified  and  it  is  not  defined  in  the  environment,  printenv  returns  exit  status  1,  else 
it  returns  status  0. 

SEE  ALSO 

sh(l),  environ(5),  csh(l) 
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NAME 

prmail  —  print  out  waiting  mail 

SYNOPSIS 

prmail  |  user  ...  | 

DESCRIPTION 

Prmail  prints  the  mail  which  waits  for  you,  or  the  specified  u^crs.  The  mail  is  not  disturbed. 

FILES 

/usr/spool/mail/#  waiting  mail  files 
SEE  ALSO 

bi£f(l),  mail(l),  from(l),  binmail(l) 
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NAME 

prof  —  display  profile  data 
SYNOPSIS 

prof  I  -a  )  [  -1  ]  I  -n  ]  I  -B  1  I  -V  [  -low  [  -high  |  ]  j  [  -*  ]  |  ohject^file  (  profile-file  ...  |  j 
DESCRIPTION 

Prof  interprets  the  file  produced  by  the  monitor{i)  subroutine.  In  the  default  case,  the  symbol 
table  in  the  named  object  file  {object-file  by  default)  is  read  and  correlated  with  the  profile  file 
{profile-file  by  default).  For  each  external  symbol,  the  percentage  of  time  spent  executing 
between  that  symbol  and  the  next  is  printed  (in  decreasing  order),  together  with  the  number  of 
times  that  routine  was  called  and  the  number  of  milliseconds  per  call.  If  more  than  one  profile 
file  is  specified,  the  output  represents  the  sum  of  the  profiles. 

To  tally  the  number  of  calls  to  a  routine,  the  program  must  be  compiled  with  the  — p  option  of 
cc,  /77or  pc.  This  option  also  means  that  the  profile  file  is  produced  automatically. 

Beware  of  quantization  errors. 

OPTIONS 

—a  Report  all  symbols  rather  than  just  external  symbols. 

—I  Sort  the  output  by  symbol  value. 

— n  sort  the  output  by  number  of  calls. 

— B  Produce  a  summary  profile  file  in  mon.sum.  This  is  really  only  useful  when  more  than 

one  profile  file  is  specified. 

—V  I  —low  [  —high  ]] 

Suppress  all  printing  and  produce  a  graphic  version  of  the  profile  on  the  standard  output 
for  display  by  the  p/oI(lG)  filters.  When  plotting,  the  numbers  low  and  high,  (by  default 
0  and  100),  select  a  percentage  of  the  profile  to  be  plotted,  with  accordingly  higher  reso¬ 
lution. 

— B  Print  routines  which  have  zero  usage  (as  indicated  by  call  counts  and  accumulated  time). 

FILES 

mon.out  for  profile 

a.out  for  namelist 

mon.sum  for  summary  profile 

SEE  ALSO 

monitor(3),  profil(2),  cc(l),  plot(lG),  gprof(l) 

BUGS 

Pro/ is  confused  by  /77  which  puts  the  entry  points  at  the  bottom  of  subroutines  and  functions. 
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NAME 

prs  —  print  an  SCCS  file 
SYNOPSIS 

/usr/sccs/prs  (  —d\data8p€c\  ]  [  — r  (5/Z>]  |  (  — e  ]  [  — 1 1  (  —a  |  file  ••• 

DESCRIPTION 

Prs  prints,  on  the  standard  output,  parts  or  all  of  an  SCCS  file  (see  8CC8file{b))  in  a  user  supplied 
format.  If  a  directory  is  named,  prs  behaves  as  though  each  file  in  the  directory  were  specified 
as  a  named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with 
».),  and  unreadable  files  are  silently  ignored.  If  a  name  of  —  is  given,  the  standard  input  is  read, 
in  which  case  each  line  is  taken  to  be  the  name  of  an  SCCS  file  or  directory  to  be  processed;  non- 
SCCS  files  and  unreadable  files  are  silently  ignored. 

OPTIONS 

Options  apply  independently  to  each  named  file. 

—d\dataspec\ 

Specifies  the  output  data  specification.  The  dataspec  is  a  string  consisting  of  SCCS  file 
data  keywords  (see  DATA  KEYWORDS^  interspersed  with  optional  user  supplied  text. 

-t\sid\ 

Specifies  the  5CCS  /Dentification  (SID)  string  of  a  delta  for  which  information  is  desired. 
If  no  SID  is  specified,  the  SID  of  the  most  recently  created  delta  is  assumed. 

— e  Requests  information  for  all  deltas  created  earlier  than  and  including  the  delta  desig¬ 

nated  via  the  — r  option. 

—1  Requests  information  for  all  deltas  created  later  than  and  including  the  delta  designated 
via  the  — r  option. 

—a  Requests  printing  of  information  for  both  removed,  that  is,  delta  type  =  R,  (see 
rmdel[\))  and  existing,  that  is,  delta  type  =  D,  deltas.  If  the  —a  option  is  not  specified, 
information  for  existing  deltas  only  is  provided. 

In  the  absence  of  the  — d  options,  prs  displays  a  default  set  of  infomation  consisting  of:  delta- 
type,  release  number  and  level  number,  date  and  time  last  changed,  user-name  of  the  person  who 
changed  the  file,  lines  inserted,  changed,  and  unchanged,  the  MR  numbers,  and  the  comments. 

DATA  KEYWORDS 

Data  keywords  specify  which  parts  of  an  SCCS  file  are  to  be  retrieved  and  output.  All  parts  of 
an  SCCS  file  (see  sccsfile{S))  have  an  associated  data  keyword.  There  is  no  limit  on  the  number 
of  times  a  data  keyword  may  appear  in  a  dataspec. 

The  information  printed  by  prs  consists  of:  1)  the  user  supplied  text;  and  2)  appropriate  values 
(extracted  from  the  SCCS  file)  substituted  for  the  recognized  data  keywords  in  the  order  of 
appearance  in  the  dataspec.  The  format  of  a  data  keyword  value  is  either  Simple  (S),  in  which 
keyword  substitution  is  direct,  or  Multuline  (M),  in  which  keyword  substitution  is  followed  by  a 
carriage  return. 

User  supplied  text  is  any  text  other  than  recognized  data  keywords.  A  tab  is  specified  by  \t  and 
carriage  return/new-line  is  specified  by  \n. 
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TABLE  1.  sees  Files  Data  Keywords 


Keyword 

Data  Item 

File  Section 

Vdue 

Format 

Dt: 

Delta  information 

Delta  Table 

Sec  below* 

S 

DL: 

Delta  line  statistics 

»* 

d^i:/djd:/JiU: 

S 

Li: 

Lines  inserted  by  Delta 

•« 

nnnnn 

s 

Ld; 

Lines  deleted  by  Delta 

M 

nnnnn 

s 

Lu: 

Lines  unchanged  by  Delta 

M 

nnnnn 

s 

DT: 

Delta  type 

H 

D  oj  R 

s 

sees  ID  string  (SID) 

M 

:R:.:L:.:B:«:S: 

s 

R: 

Release  number 

nnnn 

s 

L: 

Level  number 

M 

nnnn 

s 

B: 

Branch  number 

nnnn 

s 

S; 

Sequence  number 

»* 

nnnn 

s 

D: 

Date  Delta  created 

t* 

:Dy:/J>m:/:Dd: 

s 

Dy: 

Year  Delta  created 

** 

nn 

s 

Dm: 

Month  Delta  created 

** 

nn 

s 

Dd: 

Day  Delta  created 

** 

nn 

s 

T: 

Time  Delta  created 

«* 

:Th:::Tm:;:T8; 

S 

Th; 

Hour  Delta  created 

nn 

s 

Tm: 

Minutes  Delta  created 

W 

nn 

s 

Ts; 

Seconds  Delta  created 

nn 

s 

P; 

Programmer  who  created  Delta 

H 

logname 

s 

DS: 

Delta  sequence  number 

«« 

nnnn 

s 

DP: 

Predecessor  Delta  seq-no. 

« 

nnnn 

s 

DI: 

Seq-no.  of  deltas  incl., 
excl.y  ignored 

M 

:Dn:/:Dx:/:Dg: 

s 

:Dn: 

Deltas  Included  (seq  #) 

M 

:DS:  :DS:... 

s 

:Dx: 

Deltas  excluded  (seq  #) 

:DS:  :DS:.., 

s 

:Dg: 

Deltas  ignored  (seq  #) 

« 

:DS:  :DS:... 

s 

:MR: 

MR  numbers  for  delta 

text 

M 

:C: 

Comments  for  delta 

H 

text 

M 

:UN: 

User  names 

User  Names 

text 

M 

:FL: 

Flag  list 

Flags 

text 

M 

:Y: 

Module  type  flag 

H 

text 

S 

:MF: 

MR  validation  flag 

M 

yee  or  no 

S 

MP; 

MR  validation  pgm  name 

t* 

text 

s 

JCF: 

Keyword  error /warning  flag 

H 

ye$  or  no 

s 

:BF: 

Branch  flag 

N 

yes  or  no 

s 

:J: 

Joint  edit  flag 

M 

yee  or  no 

s 

:LK: 

Locked  releases 

M 

:R:.- 

s 

:Q: 

User  defined  keyword 

M 

text 

s 

:M: 

Module  name 

♦♦ 

text 

s 

:FB: 

Floor  boundary 

M 

:R: 

s 

:CB; 

Ceiling  boundary 

M 

:R: 

s 

:Ds: 

Default  SID 

n 

:I: 

s 

:ND: 

Null  delta  flag 

« 

yes  or  no 

s 

:FD: 

File  descriptive  text 

Comments 

text 

M 

:BD: 

Body 

Body 

text 

M 

;GB: 

Gotten  body 

♦♦ 

text 

M 

:W: 

A  form  of  string 

N/A 

s 

lA: 

A  form  of  string 

N/A 

:Z::Y;  A4:  *J:;Z: 

s 

:Z: 

uAa^(l)  string  delimiter 

N/A 

@(#) 

s 

J': 

sees  file  name 

N/A 

text 

s 

:PN: 

secs  file  path  name 

N/A 

text 

s 
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EXAMPLES 

/uBr/sccs/prs  — d^Ueers  and/or  user  IDs  for  :Fj  arci\niUN:*  s.flle 

may  produce  on  the  standard  output: 

Users  and/or  user  IDs  for  s.file  aret 

xyz 

131 

abc 

/usr/sccs/prs  --d^Newest  delta  for  pgm  :M::  :I:  Created  :Dt  By  :P:*  — r  s.flte 

may  produce  on  the  standard  output: 

Newest  delta  for  pgm  main.c:  3.7  Created  77/12/1  By  cas 
As  a  special  case: 

/usr/Bccs/prs  B.file 
may  produce  on  the  standard  output: 

D  1.1  77/12/1  00:00:00  cas  1  OOOOOO/OOOOO/OOOOO 
MRs: 

bl78- 12345 
bl79*54321 
COMMENTS: 

this  is  the  comment  line  for  s.file  initial  delta 

for  each  delta  table  entry  of  the  “D”  type.  The  only  option  argument  allowed  to  be  used  with 
the  special  case  is  the  —a  option. 

FILES 

/tmp/pr????? 

SEE  ALSO 

sccs(l),  admin(l),  delta(l),  get(l),  help(l),  sccsfile(5). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation, 

DIAGNOSTICS 

Use  Ae/p(l)  for  explanations. 


o 


246 


Last  change:  20  March  1984 


Sun  Release  2.0 


PS(1) 


USER  COMMANDS 


PS(1) 


NAME 

ps  —  process  status 
SYNOPSIS 

ps  [  acCegklsStuvwx#  |  [  kerneLname  [  |  c^dump^le  j  [  swap^le  | 

DESCRIPTION 

Ps  displays  information  about  processes.  Normally,  only  processes  that  you  have  started  are  can¬ 
didates  to  be  displayed  by  ps,  but  see  the  OPTIONS  section  below  for  how  to  get  more  informa¬ 
tion.  Specifying  a  makes  other  users’  processes  candidates  to  be  displayed;  specifying  x  includes 
processes  without  control  terminals  in  the  candidate  pool. 

All  output  formats  include,  for  each  process,  the  process  id  —  PID,  control  terminal  of  the  pro¬ 
cess  —  TT,  cpu  time  used  by  the  process  —  TIME  (this  includes  both  user  and  system  time),  the 
state  —  STAT  —  of  the  process,  and  an  indication  of  the  COMMAND  which  is  running. 

The  state  is  given  by  a  sequence  of  four  letters,  for  example,  ‘RWNA’. 

First  letter  indicates  the  runnability  of  the  process: 

R  Runnable  processes, 

T  Stopped  processes, 

P  Processes  in  page  wait, 

D  Processes  in  disk  (or  other  short  term)  waits, 

S  Processes  sleeping  for  less  than  about  20  seconds, 

I  Processes  which  are  idle  (sleeping  longer  than  about  20  seconds). 

Z  A  child  processes  that  has  terminated  and  is  waiting  for  its  parent  process  to 
do  a  wait. 

Second  letter  indicates  whether  a  process  is  swapped  out; 
blank 

(that  is,  a  space)  in  this  position  indicates  that  the  process  is  loaded  (in 
memory). 

W  Process  is  swapped  out. 

>  Process  has  specified  a  soft  limit  on  memory  requirements  and  has  exceeded 
that  limit  shows;  such  a  process  is  (necessarily)  not  swapped. 

Third  letter  indicates  whether  a  process  is  running  with  altered  CPU  scheduling  priority 
(nice): 
blank 

(that  is,  a  space)  in  this  position  indicates  that  the  process  is  running  without 
special  treatment. 

N  The  process  priority  is  reduced, 

<  The  process  priority  has  been  raised  artificially. 

Fourth  letter  indicates  any  special  treatment  of  the  process  for  virtual  memory  replacement. 

The  letters  correspond  to  options  to  the  vadvide{2)  system  call.  Currently  the 

possibilities  are: 

blank 

(that  is,  a  space)  in  this  position  stands  for  VA_NORM. 

A  Stands  for  VA^ANOM.  An  A  typically  represents  a  program  which  is  doing 
garbage  collection. 

S  Stands  for  VA^SEQL.  An  S  is  typical  of  large  image  processing  programs 
which  are  using  virtual  memory  to  sequentially  address  voluminous  data. 

KerneLname  specifies  the  location  of  the  system  namelist.  If  the  k  option  is  given,  c^dump^le 
tells  pm  where  to  look  for  core.  Otherwise,  the  core  dump  is  located  in  the  file  fvmcore  and  this 
argument  is  ignored.  Swap^le  gives  the  location  of  a  swap  file  other  than  the  default, 
Idevfdrum. 
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OPTIONS 

a  Display  information  about  all  processes  with  terminals  (ordinarily  only  one’s  own  processes 
are  displayed). 

c  Display  the  command  name,  as  stored  internally  in  the  system  for  purposes  of  accounting, 

rather  than  the  command  arguments,  which  are  kept  in  the  process’  address  space.  This  is 
more  reliable,  if  less  informative,  since  the  process  is  free  to  destroy  the  latter  information. 

C  Display  raw  CPU  time  in  the  %CPU  field  instead  of  the  decaying  average. 

e  Display  the  environment  as  well  as  the  arguments  to  the  command. 

g  Display  all  processes.  Without  this  option,  pa  only  prints  ‘interesting’  processes.  Processes 
are  deemed  to  be  uninteresting  if  they  are  process  group  leaders.  This  normally  eliminates 
top-level  command  interpreters  and  processes  waiting  for  users  to  login  on  free  terminals. 

k  Normally,  kerneLname,  defaults  to  /vmunix,  c^dump^le  is  ignored,  and  awap^le  defaults 
to  /dev/ drum.  With  the  k  option  in  effect,  these  arguments  default  to  /vmunix,  /vmcorc, 
and  /dev/drumy  respectively. 

1  Display  a  long  listing,  with  fields  PPID,  CP,  PRI,  NI,  ADDR,  SIZE,  RSS  and  WCHAN  as 
described  below. 

s  Adds  the  size  SSIZ  of  the  kernel  stack  of  each  process  (for  use  by  system  maintainers)  to 
the  basic  output  format. 

S  Display  accumulated  CPU  time  used  by  this  process  and  all  of  its  reaped  children. 

tx  Restrict  output  to  processes  whose  controlling  tty  is  x  (which  should  be  specified  as  printed 
by  ps,  for  example,  iS  for  tty3,  too  for  console,  tdO  for  ttydO,  t?  for  processes  with  no  tty, 
etc).  This  option  must  be  the  last  one  given. 

u  Display  user-oriented  output.  This  includes  fields  USER,  %CPU,  NICE,  SIZE,  and  RSS  as 
described  below. 

V  Display  a  version  of  the  output  containing  virtual  memory.  This  includes  fields  RE,  SL, 
PAGEIN,  SIZE,  RSS,  LIM,  TSIZ,  TRS,  %CPU  and  %MEM,  described  below. 

w  Use  a  wide  output  format  (132  columns  rather  than  80);  if  repeated,  that  is,  ww,  use  arbi¬ 
trarily  wide  output.  This  information  is  used  to  decide  how  much  of  long  commands  to 
print. 

X  Display  even  those  processes  with  no  terminal. 

#  A  process  number  may  be  given,  in  which  case  the  output  is  restricted  to  that  process. 
This  option  must  also  be  last. 

DISPLAY  FORMATS 

Fields  which  are  not  common  to  all  output  formats: 

USER  name  of  the  owner  of  the  process 

%CPU  cpu  utilization  of  the  process;  this  is  a  decaying  average  over  up  to  a  minute  of  previ¬ 
ous  (real)  time.  Since  the  time  base  over  which  this  is  computed  varies  (since 
processes  may  be  very  young)  it  is  possible  for  the  sum  of  all  %CPU  fields  to  exceed 
100%. 

NICE  (or  NI)  process  scheduling  increment  (see  8etpr%ority{2)  and  ntce(3C). 

SIZE  virtual  size  of  the  process  (in  1024  byte  units) 

RSS  real  memory  (resident  set)  size  of  the  process  (in  1024  byte  units) 

LIM  soft  limit  on  memory  used,  specified  via  a  call  to  getrHmii{2);  if  no  limit  has  been 

specified  then  shown  as  xx 

TSIZ  size  of  text  (shared  program)  image 

TRS  size  of  resident  (real  memory)  set  of  text 

%MEM  percentage  of  real  memory  used  by  this  process. 
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RE  residency  time  of  the  process  (seconds  in  core) 

SL  sleep  time  of  the  process  (seconds  blocked) 

PAGEIN  number  of  disk  i/o’s  resulting  from  references  by  the  process  to  pages  not  loaded  in 
core. 

UID  numerical  user-id  of  process  owner 

PPID  numerical  id  of  parent  of  process 

CP  short-term  cpu  utilization  factor  (used  in  scheduling) 

PRI  process  priority  (non-positive  when  in  non-interruptible  wait) 

ADDR  swap  address  of  the  process 

WCHAN  event  on  which  process  is  waiting  (an  address  in  the  system),  with  the  initial  part  of 
the  address  trimmed  off,  for  example,  80004000  prints  as  4000. 

F  flags  associated  with  process  as  in  <8ys/pToc.h>: 

SLOAD  0000001  in  core 

SSYS  0000002  swapper  or  pager  process 

SLOCK  0000004  process  being  swapped  out 

SSWAP  0000008  save  area  flag 

STRC  0000010  process  is  being  traced 

SWTED  0000020  another  tracing  flag 

SULOCK  0000040  user  settable  lock  in  core 
SPACE  0000080  process  in  page  wait  state 
SKEEP  0000100  another  flag  to  prevent  swap  out 
SOMASK  0000200  restore  old  mask  after  taking  signal 
SWEXIT  0000400  working  on  exiting 

SPHYSIO  0000800  doing  physical  i/o  (bio.c) 

SVFORK  0001000  process  resulted  from  vfork() 

SVFDONE  0002000  another  vfork  flag 

SNOVM  0004000  no  vm,  parent  in  a  vfork() 

SPAGI  0008000  init  data  space  on  demand,  from  inode 

SSEQL  0010000  user  warned  of  sequential  vm  behavior 

SUANOM  0020000  user  warned  of  anomalous  vm  behavior 
STIMO  0040000  timing  out  during  sleep 

SOUSIG  0100000  using  old  signal  mechanism 

SOWEUPC  0200000  owe  process  an  addupc()  call  at  next  ast 
SSEL  0400000  selecting;  wakeup/waiting  danger 

SLOGIN  0800000  a  login  process  (legit  child  of  init) 

SPTECHG  1000000  pte’s  for  process  have  changed 

A  process  that  has  exited  and  has  a  parent,  but  has  not  yet  been  waited  for  by  the  parent  is 
marked  <defunct>;  a  process  which  is  blocked  trying  to  exit  is  marked  <exiting>;  ps  makes  an 
educated  guess  as  to  the  file  name  and  arguments  given  when  the  process  was  created  by  examin¬ 
ing  memory  or  the  swap  area.  The  method  is  inherently  somewhat  unreliable  and  in  any  event  a 
process  is  entitled  to  destroy  this  information,  so  the  names  cannot  be  counted  on  too  much. 

FILES 

/v  mu  nix  system  namelist 

/dev/kmem  kernel  memory 
/dev/drum  swap  device 
/vmcore  core  file 

/dev  searched  to  find  swap  device  and  tty  names 

SEE  ALSO 

kill(l),  w(l) 
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BUGS 

Things  can  change  while  p9  is  running;  the  picture  it  gives  is  only  a  close  approximation  to  real¬ 
ity. 


250 


Last  change:  1  February  1985 


Sun  Release  2.0 


PTI(l) 


USER  COMMANDS 


PTI(l) 


NAME 

pti  —  phototypesetter  interpreter 

SYNOPSIS 

ptl  I  file  ...  ] 

DESCRIPTION 

Pti  shows  the  commands  in  a  stream  from  the  standard  output  of  troff{l)  using  troff’a  — t  option, 
interpreting  them  as  they  would  act  on  the  typesetter.  Horizontal  motions  shows  as  counts  in 
internal  units  and  are  marked  with  *<’  and  '>’  indicating  left  and  right  motion.  Vertical  space  is 
called  leading  and  is  also  indicated. 

The  output  is  really  cryptic  unless  you  are  an  experienced  C/A/T  hardware  person.  It  is  better 
to  use  troff  —a. 

SEE  ALSO 

trofT(l) 
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NAME 

ptx  —  permuted  index 
SYNOPSIS 

ptx  [  -f  I  i  -t  1  [  -w  rt  I  1  -g  rt  I  I  -o  only  |  [  -I  ignore  \  [  -b  break  |  I  -r  |  [  input  |  output  j  | 
DESCRIPTION 

Ptx  generates  a  permuted  index  of  the  contents  of  file  input  onto  file  output  (defaults  are  stan¬ 
dard  input  and  output),  Ptx  has  three  phases:  the  first  does  the  permutation,  generating  one  line 
for  each  keyword  in  an  input  line.  The  keyword  is  rotated  to  the  front.  The  permuted  file  is 
then  sorted.  Finally,  the  sorted  lines  are  rotated  so  the  keyword  comes  at  the  middle  of  the 
page.  Ptx  produces  output  in  the  form: 

.XX  ^tail"  **before  keyword"  "keyword  and  after"  "head" 

where  .xx  may  be  an  nroff{l)  or  troff{l)  macro  for  user-defined  formatting.  The  before  keyword 
and  keyword  and  after  fields  incorporate  as  much  of  the  line  as  will  fit  around  the  keyword  when 
it  is  printed  at  the  middle  of  the  page.  Tail  and  head,  at  least  one  of  which  is  an  empty  string 
are  wrapped-around  pieces  small  enough  to  fit  in  the  unused  space  at  the  opposite  end  of  the  line. 
When  original  text  must  be  discarded,  7’  marks  the  spot, 

OPTIONS 

— f  Fold  upper  and  lower  case  letters  for  sorting. 

— t  Prepare  the  output  for  the  phototypesetter;  the  default  line  length  is  100  characters. 

—wn  Use  the  next  argument,  n,  as  the  width  of  the  output  line.  The  default  line  length  is  72 

characters. 

— gn  Use  the  next  argument,  n,  as  the  number  of  characters  to  allow  for  each  gap  among  the 
four  parts  of  the  line  as  finally  printed.  The  default  gap  is  3  characters. 

--ooniy  Use  as  keywords  only  the  words  given  in  the  only  file. 

—\ignore 

Do  not  use  as  keywords  any  words  given  in  the  ignore  file.  If  the  —I  and  — o  options  are 
missing,  use  jusrllibl eign  as  the  ignore  file, 

—hbreak 

Use  the  characters  in  the  break  file  to  separate  words.  In  any  case,  tab,  newline,  and 
space  characters  are  always  used  as  break  characters. 

— r  Take  any  leading  nonblank  characters  of  each  input  line  to  be  a  reference  identifier  (as  to 

a  page  or  chapter)  separate  from  the  text  of  the  line.  Attach  that  identifier  as  a  5th  field 
on  each  output  line. 

FILES 

/bin/sort 

/usr/lib/eign 

BUGS 

Line  length  counts  do  not  account  for  overstriking  or  proportional  spacing. 
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NAME 

pwd  —  print  working  directory  name 

SYNOPSIS 

pwd 

DESCRIPTION 

Pwd  prints  the  pathname  of  the  working  (current)  directory* 

If  you  are  using  you  can  use  the  dira  builtin  command  to  do  the  same  job  more  quickly; 

BUT  dirs  can  give  a  different  answer  in  the  rare  case  that  the  current  directory  or  a  containing 
directory  was  moved  after  the  shell  descended  into  it*  This  is  because  pwd  searches  back  up  the 
directory  tree  to  report  the  true  pathname,  whereas  dirs  remembers  the  pathname  from  the  last 
cd  command.  The  example  below  illustrates  the  differences* 

%  cd  /uar/wendy /January/reports 
%  pwd 

/usr/wendy/January /reports 

%  dire 

/January /re  ports 

%  mv  ""/January  ""/february 
%  pwd 

/  usr/wendy/february/reports 

%  dlrs 

"^/January/reports 

% 

Pwd  and  dirs  also  give  different  answers  when  you  change  directory  through  a  symbolic  link*  For 
example: 

%  cd  /usr/wendy/January /reports 
%  pwd 

/usr/wendy/january /reports 

%  dirs 

/j  an  u  ary  /re  ports 

%  Is  —1  /usr/wendy/january 

Irwxrwxrwx  1  wendy  17  Jan  30  1983  /usr/wendy/january  ->  /usr/wendy/1984/jan/ 

%  cd  /usr/wendy/january 
%  pwd 

/usr/wendy/l984/jan 

%  dirs 

/usr/wendy/january 

They  may  also  report  different  pathnames  if  you  have  changed  directories  through  a 
symbolic  link, 

SEE  ALSO 

cd(l),  csh(l),  getwd(3) 
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NAME 

px  —  Pascal  interpreter 
SYNOPSIS 

px  [  obj  I  argument  j  | 

DESCRIPTION 

Px  interprets  the  abstract  machine  code  generated  by  pi.  The  first  argument  is  the  file  to  be 
interpreted,  and  defaults  to  ohj\  remaining  arguments  are  available  to  the  Pascal  program  using 
the  built-ins  argv  and  argc.  Px  is  also  invoked  by  pix  when  running  ‘load  and  go’. 

If  the  program  terminates  abnormally  an  error  message  and  a  control  flow  backtrace  are  printed. 
The  number  of  statements  executed  and  total  execution  time  are  printed  after  normal  termina¬ 
tion.  The  p  option  of  pi  suppresses  all  of  this  except  the  message  indicating  the  cause  of  abnor¬ 
mal  termination. 

FILES 

obj  default  object  file 

pmon.out  profile  data  file 

SEE  ALSO 

The  Pascal  User's  Manual  in  the  Sun  Pascal  Manual. 
pi(l),  pix(l) 

DIAGNOSTICS 

Most  run-time  error  messages  are  self-explanatory.  Some  of  the  more  unusual  ones  are: 

Reference  to  an  inactive  file 

A  file  other  than  input  or  output  was  used  before  a  call  to  reset  or  rewrite. 

Statement  count  limit  exceeded 

The  limit  of  500,000  executed  statements  (which  prevents  excessive  looping  or  recursion) 
has  been  exceeded. 

Bad  data  found  on  integer  read 
Bad  data  found  on  real  read 

Usually,  non-numeric  input  was  found  for  a  number.  For  reals,  Pascal  requires  digits 
before  and  after  the  decimal  point  so  that  numbers  like  M’  or  ‘21.’  evoke  the  second  diag¬ 
nostic. 

panic:  Some  message 

Indicates  a  interna!  inconsistency  detected  in  px  probably  due  to  a  Pascal  system  bug. 

BUGS 

Post-mortem  traceback  is  not  limited;  infinite  recursion  leads  to  almost  infinite  traceback. 
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NAME 

pxp  —  Pascal  execution  profiler 
SYNOPSIS 

pxp  I  — acdeQLnstuw.  |  [  —23450780  ]  [  — *  |  name  ...  j  j  name.p 
DESCRIPTION 

Pxp  can  be  used  to  obtain  execution  profiles  of  Pascal  programs  or  as  a  pretty-printer.  To  pro¬ 
duce  an  execution  profile  all  that  is  necessary  is  to  translate  the  program  specifying  the  s  option 
to  pc,  pi,  or  piXf  execute  the  program,  and  then  type  the  command 
tutorial%  pxp  —is  name.p 

Pxp  generates  a  reformatted  listing  if  none  of  the  c,  t,  or  z  options  are  specified;  thus 
tutorial%  pxp  old.p  >  new.p 

places  a  pretty-printed  version  of  the  program  in  oW.p  in  the  file  new*p. 

OPTIONS 

The  use  of  the  following  options  of  pjp  is  discussed  in  the  Pascal  User^s  Manual  in  the  Sun  Pas¬ 
cal  Manual. 

—a  Print  the  bodies  of  all  procedures  and  functions  in  the  profile;  even  those  which  were  never 
executed. 

— c  Extract  profile  data  from  the  file  core, 

— d  Include  declaration  parts  in  a  profile. 

— e  Eliminate  include  directives  when  reformatting  a  file;  the  Include  is  replaced  by  the  refor¬ 
matted  contents  of  the  specified  file. 

— f  Fully  parenthesize  expressions. 

— J  Left  justify  all  procedures  and  functions. 

— L  Map  all  identifiers  and  keywords  to  lower  case. 

— n  Eject  a  new  page  as  each  file  is  included;  in  profiles,  print  a  blank  line  at  the  top  of  the 
page. 

—0  Strip  comments  from  the  input  text. 

— t  Print  a  table  summarizing  procedure  and  function  call  counts. 

— u  Card  image  mode;  only  the  first  72  characters  of  input  lines  are  used. 

— w  Suppress  warning  diagnostics. 

—0  Generate  an  execution  profile.  If  no  names  are  given  the  profile  is  of  the  entire  program.  If 
a  list  of  names  is  given,  then  only  the  specified  procedures  or  functions  and  the  contents 
of  the  specified  include  files  will  appear  in  the  profile. 

— _  Underline  keywords. 

— d  Use  d  spaces  (where  d  is  a  digit,  2  <  d  <  9)  as  the  basic  indenting  unit.  The  default  is  4. 

FILES 

name.p  input  file 

name.!  include  file(s) 

name.h  include  file(s) 

pmon.out  profile  data 

core  profile  data  source  for  — c  option 

/usr/lib/how_pxp  information  on  basic  usage 
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SEE  ALSO 

The  Pascal  User’s  Manual  in  the  Sun  Pascal  Manual. 
pc(l),  pi(l),  px(l) 

DIAGNOSTICS 

For  a  basic  explanation  do 
tutorial%  pxp 

Error  diagnostics  include  ‘No  profile  data  in  file’  with  the  c  option  if  the  s  option  was  not 
enabled  to  pi;  ‘Not  a  Pascal  system  core  file’  if  the  core  is  not  from  a  pz  execution;  ‘Program  and 
count  data  do  not  correspond’  if  the  program  was  changed  after  compilation,  before  profiling;  or 
if  the  wrong  program  is  specified. 

BUGS 

Does  not  place  multiple  statements  per  line. 

Procedures  and  functions  as  parameters  are  printed  without  nested  parameter  lists,  as  in  the 
obsolete  Jensen  and  Wirth  syntax. 
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NAME 

pxref  —  Pascal  cross-reference  program 

SYNOPSIS 

pxref  [  —  I  name 

DESCRIPTION 

Pxref  makes  a  line  numbered  listing  and  a  cross-reference  of  identifier  usage  for  the  program  in 
name.  The  optional  ’  argument  suppresses  the  listing.  The  keywords  goto  and  label  are 
treated  as  identifiers  for  the  purpose  of  the  cross-reference.  Include  directives  are  not  processed, 
but  cause  the  placement  of  an  entry  indexed  by  *#include’  in  the  cross-reference. 

SEE  ALSO 

The  Pascal  User's  Manual  in  the  Sun  Fortran  and  Pascal  Manual. 

BUGS 

Identifiers  are  trimmed  to  10  characters. 
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NAME 

ranlib  —  convert  archives  to  random  libraries 

SYNOPSIS 

ranlib  archive  ... 

DESCRIPTION 

Ranlib  converts  each  archive  to  a  form  which  the  loader  can  load  more  rapidly.  Ranlib  does  this 
by  adding  a  table  of  contents  called  _.SYMDEF  to  the  beginning  of  the  archive.  Ranlib  uses 
ar(I)  to  reconstruct  the  archive,  so  that  sufficient  temporary  file  space  must  be  available  in  the 
file  system  which  contains  the  current  directory. 

SEE  ALSO 

ld(I),  ar(l),  lorder(l) 

BUGS 

Because  generation  of  a  library  by  ar  and  randomization  of  the  library  by  ranlib  are  separate 
processes,  phase  errors  are  possible.  The  loader.  Id,  warns  when  the  modification  date  of  a 
library  is  more  recent  than  the  creation  date  of  its  dictionary;  but  this  means  that  you  get  the 
warning  even  if  you  only  copy  the  library. 
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NAME 

rastrepi  —  magnify  a  raster  image  by  2  times 
SYNOPSIS 

rastrepi  [  input-file  |  output-file  |] 

DESCRIPTION 

Rastrepi  reads  input-file  (or  the  standard  input  if  input-file  is  not  specified)  which  should  be  in 
rasterfile  format  (see  f  uarf  include  f  raster  file. K),  replicates  each  pixel  in  both  the  x  and  y  direc¬ 
tions,  and  writes  the  resulting  rasterfile  to  output-file  (or  the  standard  output  if  output-file  is  not 
specified). 

EXAMPLES 

tutorial%  acreendump  }  rastrepi  {  Ipr  — Pversatec  — v 

sends  a  rasterfile  containing  the  current  frame  buffer  to  the  Versatec  plotter,  doubling  the  size  of 
the  image  so  that  it  fills  a  single  page. 

SEE  ALSO 

screendump(l),  screenload(l),  Ipr(l) 
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NAME 

ratfor  —  rational  Fortran  dialect 
SYNOPSIS 

ratfor  [  ]  |  — C  j  [  — h  ]  |  filename  | 

DESCRIPTION 

Ratfor  converts  a  rational  dialect  of  Fortran  into  ordinary  irrational  Fortran.  Ratfor  provides 
control  flow  constructs  essentially  identical  to  those  in  C: 

statement  grouping: 

{  statement;  statement;  statement  } 

decision-making: 

if  (condition)  statement  (  else  statement ) 
switch  (integer  value)  { 

case  integer:  statement 

(  default:  j  statement 

} 

loops:  while  (condition)  statement 

for  (expression;  condition;  expression)  statement 

do  limits  statement 

repeat  statement  [  until  (condition)  [ 

break 

next 

and  some  syntactic  sugar  to  make  programs  easier  to  read  and  write: 

free  form  input: 

multiple  statements/line;  automatic  continuation 

comments: 

#  this  is  a  comment 

translation  of  relattonals: 

>,  >=,  etc.,  become  ,GT.,  .GE.,  etc. 

return(expression) 

returns  expression  to  caller  from  function 
define:  define  name  replacement 

Include: 

include  filename 

Ratfor  is  best  used  with  /77(l). 

OPTIONS 

—6c  Use  the  character  c  as  the  continuation  character  in  column  6  when  translating  to  For¬ 
tran.  The  default  is  to  use  the  &  character  as  a  continuation  character. 

— C  Pass  Ratfor  comments  through  to  the  translated  code. 

— h  Translate  Ratfor  string  constants  to  Hollerith  constants  of  the  form  nnnhsfrinir.  Other¬ 

wise  just  pass  the  strings  through  to  the  translated  code. 

SEE  ALSO 

f77(l) 

B.  W.  Kernighan  and  P.  J.  Plauger,  Software  Tools,  Addison-Wesley,  1976. 
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NAME 

rep  —  remote  file  copy 

SYNOPSIS 

rep  filel  file2 

rep  [  — r  ]  file  directory 

DESCRIPTION 

Rep  copies  files  between  machines.  Each  file  or  directory  argument  is  either  a  remote  file  name 
of  the  form  “rhost:path’\  or  a  local  file  name  (containing  no  characters,  or  a  7’  before  any 
‘:’s.) 

If  the  —r  is  specified  and  any  of  the  source  files  are  directories,  rep  copies  each  subtree  rooted  at 
that  name;  in  this  case  the  destination  must  be  a  directory. 

If  path  is  not  a  full  path  name,  it  is  interpreted  relative  to  your  login  directory  on  rhosi,  A  path 
on  a  remote  host  may  be  quoted  (using  \,  or  ')  so  that  the  metacharacters  are  interpreted 
remotely. 

Rep  does  not  prompt  for  passwords;  your  current  local  user  name  must  exist  on  rhoet  and  allow 
remote  command  execution  via  rsA(lC). 

Rep  handles  third  party  copies,  where  neither  source  nor  target  files  are  on  the  current  machine. 
Hostnames  may  also  take  the  form  “rhost.rname*’  to  use  rname  rather  than  the  current  user 
name  on  the  remote  host. 

Please  note:  rep  is  meant  to  copy  from  one  host  to  another;  if  by  some  chance  you  try  to  copy  a 
file  on  top  of  itself,  you  will  end  up  with  a  severely  corrupted  file  (for  example,  if  you  executed 
the  following  command  from  host  george:  ‘george%  rep  testfile  george:/usr/me/testfile’). 
Remember  where  you  are  at  all  times  (putting  your  hostname  in  your  prompt  helps  with  this)! 

SEE  ALSO 

ftp(lC),  rsh(lC),  rlogin(lC) 

BUGS 

Doesn’t  detect  all  cases  where  the  target  of  a  copy  might  be  a  file  in  cases  where  only  a  directory 
should  be  legal. 

Is  confused  by  any  output  generated  by  commands  in  a  .login,  .profile,  or  .eshre  file  on  the 
remote  host. 

Rep  doesn’t  copy  ownership,  mode,  and  timestamps  to  the  new  files. 

Rep  requires  that  the  source  host  have  permission  to  execute  commands  on  the  remote  host 
when  doing  third-party  copies. 
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NAME 

readnews  —  read  news  articles 
SYNOPSIS 

readnews  |  —a  date  ]  |  — n  newsgroups  |  [  — t  tities  |  (  — IprxhfuM  |  1  — «  I  mailer  ]  | 
readnews  — s 
DESCRIPTION 

Readnews  without  argument  displays  unread  articles, 
readnews  — s  displays  the  newsgroup  subscription  list. 

Readnews  maintains  a  .newsre  file  in  your  home  directory  that  specifies  all  news  articles  already 
read,  .newsre  is  updated  at  the  end  of  each  news  reading  session  in  which  the  —x  or  —1  options 
weren’t  specified.  If  the  NEWSRC  environment  variable  is  present,  it  should  be  the  path  name  of 
a  file  to  be  used  in  place  of  .newsre. 

An  options  line  may  be  placed  in  the  .newsre  file.  The  options  line  starts  with  the  word  options 
(left  justified)  followed  by  the  list  of  standard  options  just  as  they  would  be  typed  on  the  reorf- 
news  command  line.  The  list  of  options  may  include:  the  ~n  flag  along  with  a  newsgroup  list;  a 
favorite  interface  to  use  for  reading  the  news;  and/or  the  — r  or  — t  flag.  Continuation  lines  are 
specified  by  following  lines  beginning  with  a  space  or  tab  character.  Similarly,  options  can  be 
specified  in  the  NEWSOPTS  environment  parameter.  Options  on  the  command  line  override 
options  in  the  .newsre  file  and  options  in  the  .newsre  file  override  options  in  the  NEWSOPTS 
environment  parameter. 

When  you  use  the  reply  command  of  the  ma»7(l)  or  /bin/mail(l)  interfaces,  readnews  uses  the 
MAILER  environment  parameter  to  determine  which  mailer  to  use.  The  default  is  usually  mail. 

You  can  specify  a  particular  paging  program  for  paging  through  articles.  The  PAGER  environ¬ 
ment  parameter  should  be  set  to  the  name  of  the  paging  program.  The  name  of  the  article  is 
referenced  with  a  *%’,  as  in  the  — c  option.  If  no  *%’  is  present,  the  article  is  piped  to  the  pro¬ 
gram.  Paging  may  be  disabled  by  setting  PAGER  to  a  null  value. 

OPTIONS 

Some  of  the  option  flags  determine  which  of  the  several  interfaces  you  can  use  for  reading  your 
news.  The  news  system  has  its  own  interface  which  is  used  if  no  other  choice  is  made,  otherwise 
one  of  these  options  can  be  used: 

— M  An  interface  to  mat7(l). 

— c  A  /6tn/fnai7(l)— like  interface. 

— c  ‘mailer’ 

All  selected  articles  written  to  a  temporary  file.  Then  the  mailer  is  invoked.  The  name 
of  the  temporary  file  is  referenced  with  a  *%’.  Thus,  ‘mail  -f  %’  will  invoke  mail  on  a 
temporary  file  consisting  of  all  selected  messages. 

Other  options  govern  the  behavior  of  readnews  itself,  as  follows: 

— p  Send  all  selected  articles  to  the  standard  output  with  no  questions  asked. 

—1  Display  only  the  titles.  Do  not  update  the  .netware  file. 

— r  display  the  articles  in  reverse  order. 

— f  Do  not  display  any  followup  article 

— h  Display  articles  in  a  less  verbose  format  (intended  for  terminals  running  at  300  baud). 

— u  Update  the  .netware  file  every  5  minutes,  in  case  of  an  unreliable  system.  Note  that  if  the 

.newsre  file  is  updated,  the  x  command  will  not  restore  it  to  its  original  contents. 
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The  following  flags  determine  the  selection  of  articles: 

— n  newsgroups 

Select  all  articles  that  belong  to  newsgroups, 

— t  titles 

Select  all  articles  whose  titles  contain  one  of  the  strings  specified  by  titles. 

—a  I  date  j 

Select  all  articles  that  were  posted  past  the  given  date  (in  mm/dd  format). 

—x  Ignore  .newsrc  file.  That  is,  select  articles  that  have  already  been  read  as  well  as  new 
ones. 

COMMANDS 

This  section  lists  the  commands  you  can  type  to  the  readnews  and  /bin/mail  interface  prompts. 
The  readnews  interface  suggests  some  common  commands  in  brackets.  Just  typing  carriage- 
return  is  the  same  as  typing  the  first  command.  For  example,  ‘jynqj’  means  that  the  commands 
y  (yes),  ‘n'  (no),  and  ‘q’  (quit)  are  common  responses,  and  that  ‘y’  is  the  default.  Here  are  the 
commands  and  their  meanings: 

y  Yes  —  displays  current  article  and  goes  on  to  next. 

n  No  —  goes  on  to  next  article  without  displaying  current  one.  In  the  /6in/mai7  interface, 
this  means  'go  on  to  the  next  article’,  which  has  the  same  effect  as  ‘y’  or  just  typing 
carriage-return. 

q  Quit  —  the  ^newsrc  file  is  updated  if  -1  or  — x  were  not  on  the  command  line, 

c  Cancel  the  article  —  only  the  author  or  the  super  user  can  do  this. 

Reply  —  reply  to  article’s  author  via  mail.  Readnews  calls  up  your  EDITOR  with  a 
header  specifying  To,  Subject,  and  References  lines  taken  from  the  message.  You  may 
change  or  add  headers,  as  appropriate.  You  add  the  text  of  the  reply  after  the  blank 
line,  and  then  exit  the  editor.  The  resulting  message  is  mailed  to  the  author  of  the  arti¬ 
cle. 

Reply  directly  —  readnews  calls  up  the  mail  program  (or  the  program  specified  in  the 
$MAILER  environment  variable)  so  that  you  can  reply  to  the  author.  Type  the  text  of 
the  reply  and  then  control-D. 

Submit  a  follow  up  article.  Normally  you  should  leave  off  the  title,  since  the  system  gen¬ 
erates  one  for  you.  Readnews  calls  up  your  EDITOR  so  that  you  can  compose  the  text  of 
the  followup. 

fd  Followup  directly,  without  edited  headers.  This  is  like  /,  but  the  headers  of  the  article 
are  not  included  in  the  editor  buffer. 

N  [newsgroup] 

Go  to  the  next  newsgroup  or  named  newsgroup. 

s  [file]  Save  —  the  article  is  appended  to  the  named  file.  The  default  filename  is  Articles.  If 
the  first  character  of  the  filename  is  'j’,  the  rest  of  the  filename  is  taken  as  the  name  of  a 
program,  which  is  executed  with  the  text  of  the  article  as  standard  input.  If  the  first 
character  of  the  filename  is  7\  it  is  taken  as  a  full  path  name  of  a  file.  If  the  SNEWSBOX 
environment  variable  is  set  to  a  full  path  name,  and  the  filename  contains  no  */’,  the  file 
is  saved  in  SNEWSBOX,  otherwise,  it  is  saved  relative  to  $HOME. 

#  Report  the  name  and  size  of  the  newsgroup, 
e  Erase  —  forget  that  this  article  was  read, 
h  Print  a  more  verbose  header. 

H  Print  a  very  verbose  header,  containing  all  known  information  about  the  article. 


rd 

f  [title] 
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U  Unsubscribe  from  this  newsgroup.  Also  goes  on  to  the  next  newsgroup. 

d  Read  a  digest.  Breaks  up  a  digest  into  separate  articles  so  you  can  read  and  reply  to 
each  piece. 

D  Decrypt  —  invokes  a  Caesar  decoding  program  on  the  body  of  the  message.  This  is  used 
to  decrypt  rotated  jokes  posted  to  net.jokes.  Such  jokes  are  usually  obscene  or  otherwise 
offensive  to  some  groups  of  people,  and  so  are  rotated  to  avoid  accidental  decryption  by 
people  who  would  be  offended.  The  title  of  the  joke  should  indicate  the  nature  of  the 
problem,  enabling  people  to  decide  whether  to  decrypt  it  or  not. 

Normally  the  Caesar  program  does  a  character  frequency  count  on  each  line  of  the  arti¬ 
cle  separately,  so  that  lines  which  are  not  rotated  will  be  shown  in  plain  text.  This  works 
well  unless  the  line  is  short,  in  which  case  it  sometimes  gets  the  wrong  rotation.  An 
explicit  number  rotation  (usually  13)  may  be  given  to  force  a  particular  shift. 

V  Print  the  current  version  of  the  news  software. 

!  Shell  escape. 

number 

Go  to  number. 

+[n]  Skip  n  articles.  The  articles  skipped  are  recorded  as  ‘unread’  and  will  be  offered  to  you 
again  the  next  time  you  read  news. 

—  Go  back  to  last  article.  This  is  a  toggle,  typing  it  twice  returns  you  to  the  original  arti¬ 
cle. 

X  Exit  —  like  quit  except  that  *newsrc  is  not  updated. 

X  system 

Transmit  article  to  the  named  system. 

The  c,  f,  fd,  r,  rd,  e,  h,  H,  and  s  commands  can  be  followed  by  — ’s  to  refer  to  the  previous  arti¬ 
cle.  Thus,  when  replying  to  an  article  using  the  readnews  interface,  you  should  normally  type 
‘r— ’  (or  ‘re-’)  since  by  the  time  you  enter  a  command,  you  are  being  offered  the  next  article. 

EXAMPLES 

readnews 

Read  all  unread  articles  using  the  readnews{l)  interface.  The  .newsrc  file  is  updated  at 
the  end  of  the  session. 

readnews  — c  ed  %  —1 

Use  the  ed(l)  text  editor  on  a  file  containing  the  titles  of  all  unread  articles.  The  .newsrc 
file  is  not  updated  at  the  end  of  the  session. 

readnewa  —n  all  ffa.all  —M  — r 

Read  all  unread  articles  except  articles  whose  newsgroups  begin  with  IB  fa  .  via  m(nY(l) 
in  reverse  order.  The  .ne«;^rc  file  is  updated  at  the  end  of  the  session. 

readnewB  — p  — n  all  —a  last  thursday 

Print  every  unread  article  since  last  Thursday,  The  .newsrc  file  is  updated  at  the  end  of 
the  session. 

readnews  — p  >  /dev/null  St 

Discard  all  unread  news.  This  is  useful  after  returning  from  a  long  trip. 

FILES 

/usT/s\>oo\/neyfs/newsgroup/numb€r  News  articles 

/usr /lib/news/active  Active  newsgroups  and  numbers  of  articles 

/usr/lib/ncws/help  Help  file  for  readnews{l)  interface 

"/.newsrc  Options  and  list  of  previously  read  articles 
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SEE  ALSO 

checknews(l),  inews(l),  sendnews(8),  recnews(8),  uurec(8),  mai{(l),  news(S),  newsrc(5) 
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NAME 

recnews  —  receive  unprocessed  articles  via  mail 


SYNOPSIS 

/uar/Ilb/news/recnewa  [  newsgroup  [  sender  [  ] 


DESCRIPTION 

Recnews  reads  a  letter  from  the  standard  input;  determines  the  article  title,  sender,  and  news- 
group;  and  gives  the  body  to  inews  with  the  right  arguments  for  insertion. 

If  newsgroup  is  omitted,  the  to  line  of  the  letter  is  used.  If  sender  is  omitted,  the  sender  is  deter¬ 
mined  from  the  from  line  of  the  letter.  The  title  is  determined  from  the  subject  line. 


SEE  ALSO 

inews(l),  uurec(8),  sendnews(8),  readnews(l),  checknews(l) 
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NAME 

refer  —  find  and  insert  literature  references  in  documents 
SYNOPSIS 

refer  [  — ar  }  [  — b  |  [  --c$tring  j  (  — e  |  [  — ka:  ]  [  —lm,n  [  [  ~p  |  |  — n  ]  [  skeys  [  file 
DESCRIPTION 

Refer  is  a  preprocessor  for  nro^(l),  or  troff{l)f  that  finds  and  formats  references.  The  input  files 
(standard  input  by  default)  are  copied  to  the  standard  output,  except  for  lines  between  •[  and 
command  lines.  Such  lines  are  assumed  to  contain  keywords  as  for  lookbib{l\  and  are  replaced 
by  information  from  a  bibliographic  data  base.  The  user  can  avoid  the  search,  override  fields 
from  it,  or  add  new  fields.  The  reference  data,  from  whatever  source,  is  assigned  to  a  set  of  trojff 
strings.  Macro  packages  such  as  ma(7)  print  the  finished  reference  text  from  these  strings.  A 
flag  is  placed  in  the  text  at  the  point  of  reference.  By  default,  the  references  are  indicated  by 
numbers. 

When  refer  is  used  with  egn(l),  negn(l),  or  refer  should  be  used  first  in  the  sequence,  to 

minimize  the  volume  of  data  passed  through  pipes. 

OPTIONS 

— ar  Reverse  the  first  r  author  names  (Jones,  J.  A.  instead  of  J.  A.  Jones).  If  r  is  omitted,  all 

author  names  are  reversed. 

— b  Bare  mode  —  do  not  put  any  flags  in  text  (neither  numbers  or  labels). 

—cstring 

Capitalize  (with  Small  Caps)  the  fields  whose  key-letters  are  in  string. 

— e  Accumulate  references  instead  of  leaving  the  references  where  encountered,  until  a 

sequence  of  the  form: 

•I 

$LIST$ 

•1 

is  encountered,  and  then  write  out  all  references  collected  so  far.  Collapse  references  to 
the  same  source. 

— ka?  Instead  of  numbering  references,  use  labels  as  specified  in  a  reference  data  line  beginning 

with  the  characters  %x;  By  default,  z  is  L. 

Instead  of  numbering  references,  use  labels  from  the  senior  author’s  last  name  and  the 
year  of  publication.  Only  the  first  m  letters  of  the  last  name  and  the  last  n  digits  of  the 
date  are  used.  If  either  of  m  or  n  is  omitted,  the  entire  name  or  date,  respectively,  is 
used. 

— p  Take  the  next  argument  as  a  file  of  references  to  be  searched.  The  default  file  is 
searched  last. 

— n  Do  not  search  the  default  file. 

-•Bkeys  Sort  references  by  fields  whose  key-letters  are  in  the  keys  string,  and  permute  reference 
numbers  in  the  text  accordingly.  Using  this  option  implies  the  — e  option.  The  key- 
letters  in  keys  may  be  followed  by  a  number  indicating  how  many  such  fields  are  used, 
with  a  +  sign  taken  as  a  very  large  number.  The  default  is  AD,  which  sorts  on  the 
senior  author  and  date.  To  sort  on  all  authors  and  then  the  date,  for  instance,  use  the 
options  — lA+T. 

FILES 

/usr/dict/papers  directory  of  default  publication  lists  and  indexes 

/usr/lib/refer  directory  of  programs 
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NAME 

rev  —  reverse  lines  of  a  file 

SYNOPSIS 

rev  I  file  ]  ... 

DESCRIPTION 

Rev  copies  the  named  files  to  the  standard  output,  reversing  the  order  of  characters  in  every  line. 
If  no  file  is  specified,  the  standard  input  is  copied. 
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NAME 

riogin  —  remote  login 
SYNOPSIS 

riogin  rhost  [  — ec  |  |  — I  username  |  [  —8  ] 


rkost  [  — I  username  ]  [  —8  ] 

DESCRIPTION 

Riogin  connects  your  terminal  on  the  current  local  host  system  Ihost  to  the  remote  host  system 
rhost. 


Each  host  has  a  file  /etc/ hosts. equiv  which  contains  a  list  of  rhost^s  with  which  it  shares  account 
names.  (The  host  names  must  be  the  standard  names  as  described  in  r^A(lC).)  When  you  riogin 
as  the  same  user  on  an  equivalent  host,  you  don’t  need  to  give  a  password.  Each  user  may  also 
have  a  private  equivalence  list  in  a  file  .rhosts  in  his  login  directory.  Each  line  in  this  file  should 
contain  an  rhost  and  a  username  separated  by  a  space,  giving  additional  cases  where  logins 
without  passwords  are  to  be  permitted.  If  the  originating  user  and  host  is  not  found  in  these 
files,  the  remote  machine  will  prompt  for  a  password  as  in  login[l).  To  avoid  some  security 
problems,  the  .rhosts  file  must  be  owned  by  either  the  remote  user  or  root  and  may  not  be  a 
symbolic  link. 

Your  remote  terminal  type  is  the  same  as  your  local  terminal  type  (as  given  in  your  environment 
TERM  variable).  All  echoing  takes  place  at  the  remote  site,  so  that  (except  for  delays)  the  riogin 
is  transparent.  Flow  control  via  "S  and  "Q  and  flushing  of  input  and  output  on  interrupts  are 
handled  properly. 


ESCAPES 

Lines  starting  with  the  tilde  character  are  ‘escape  sequences’  (the  escape  character  can  be 
changed  via  the  — e  options): 

Disconnect  from  the  remote  host  —  this  is  not  the  same  as  a  logout,  because  the  local 
host  breaks  the  connection  with  no  warning  to  the  remote  end. 

"Z  Suspend  the  login  session  (only  if  you  are  using  the  C-Shell).  Susp  is  your  ‘suspend’  char¬ 
acter  —  usually  control-Z  —  see  tty{\). 

Suspend  the  input  half  of  the  login,  but  output  will  still  be  seen  (only  if  you  are  using  the 
C-Shell).  Dsusp  is  your  ‘deferred  suspend’  character  —  usually  controI-Y  —  see  ^^i/(l). 

OPTIONS 

—1  Specifies  a  different  user  name  [username ,  in  the  synopsis)  for  the  remote  login.  If  you  do 
not  use  this  option,  the  remote  username  used  is  the  same  as  your  local  username. 

—e  Specifies  a  different  escape  character  (c,  in  the  synopsis)  for  the  line  used  to  disconnect 
from  the  remote  host. 


—8  Pass  eight- bit  data  across  the  net  instead  of  seven-bit  data. 

SEE  ALSO 

rsh(lC),  stty(l) 


FILES 

/usr/hosts/» 
/etc/hosts 
/etc/hosts. equiv 
""/•r  hosts 
/etc/services 


for  rhost  version  of  the  command 

to  translate  hostname  to  network  address 

list  of  rhosts  with  shared  account  names 

private  list  of  rhost s  with  shared  account  names 

to  translate  service  name  tcp/rlogin  to  network  port  number 


BUGS 
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This  implementation  can  only  use  the  TCP  network  service. 
More  terminal  characteristics  should  be  propagated. 


270 


Last  change:  1  February  1985 


Sun  Release  2.0 


RM(1) 


USER  COMMANDS 


RM(1) 


NAME 

rm,  rmdir  —  remove  (unlink)  files  or  directories 
SYNOPSIS 

rm  I  — f  I  [  — r  I  I  — 1  ]  (  —  i  file  ••• 
rmdir  dir 
DESCRIPTION 

rm.lr.LX  ”rm  command**  ****  Vm—  remove  file  or  directory**  rm.l:.IX  **remove  file  or  directory** 
’’remove  file  or  directory  —  rm**  rm.lr.DC  **delete  file  or  directory**  ****  ’’delete  file  or  direc¬ 
tory  —  rm**  Rm  removes  the  directory  entries  for  one  or  more  files.  If  an  entry  was  the  last  link 
to  the  file,  the  file  is  destroyed.  Rm  — r  and  rmdir  remove  entries  for  directories. 

To  remove  a  file,  you  must  have  write  permission  in  its  directory;  but  you  don’t  need  read  or 
write  permission  on  the  file  itself.  If  you  don’t  have  write  permission  on  the  file  and  the  standard 
input  is  a  terminal,  rm  displays  the  file’s  permissions  and  waits  for  you  to  type  in  a  response.  If 
your  response  begins  with  ‘y’  the  file  is  deleted;  otherwise  the  file  is  left  alone. 

To  remove  a  full  directory,  use  rm  with  the  — r  option  (see  below).  Rmdir  removes  the  named 
directory  only  if  it  is  empty, 

OPTIONS 

The  following  are  options  for  rm: 

—t  Force  files  to  be  removed,  without  displaying  permissions,  asking  questions,  or  reporting 
errors. 

— r  Recursively  delete  the  entire  contents  of  the  specified  directory  and  the  directory  itself. 

—I  Ask  whether  to  delete  each  file,  or,  under  — r,  whether  to  examine  each  directory.  Some¬ 

times  called  the  interactive  option. 

—  Treat  all  the  following  arguments  as  filenames  —  so  that  you  can  specify  filenames  start¬ 
ing  with  a  minus. 

WARNING 

It  is  forbidden  to  remove  the  file  merely  to  avoid  the  antisocial  consequences  of  inadvertently 
doing  something  like  ‘rm  — r 

SEE  ALSO 

rmdir(l),  rmdir(2),  unlink(2) 
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NAME 

rmdel  —  remove  a  delta  from  an  SCCS  file 
SYNOPSIS 

/uar/sccs/rmdel  — rSID  file  ... 

DESCRIPTION 

Rmdel  removes  the  delta  specified  by  the  SID  from  each  named  SCCS  file.  The  delta  to  be 
removed  must  be  the  newest  (most  recent)  delta  in  its  branch  in  the  delta  chain  of  each  named 
SCCS  file.  In  addition,  the  SID  specified  must  not  be  that  of  a  version  being  edited  for  the  pur¬ 
pose  of  making  a  delta  (that  is,  if  a  p-fi(e  (see  (re^(l))  exists  for  the  named  SCCS  file,  the  SID 
specified  must  not  appear  in  any  entry  of  the  p-file). 

If  a  directory  is  named,  rmdel  behaves  as  though  each  file  in  the  directory  were  specified  as  a 
named  file,  except  that  non-SCCS  files  (last  component  of  the  path  name  does  not  begin  with  a.) 
and  unreadable  files  are  silently  ignored.  If  a  name  of  —  is  given,  the  standard  input  is  read; 
each  line  of  the  standard  input  is  taken  to  be  the  name  of  an  SCCS  file  to  be  processed;  non-SCCS 
files  and  unreadable  files  are  silently  ignored. 

The  exact  permissions  necessary  to  remove  a  delta  are  documented  in  the  Source  Code  Control 
System  User^s  Guide,  Simply  stated,  they  are  either  1)  if  you  make  a  delta  you  can  remove  it;  or 
2)  if  you  own  the  file  and  directory  you  can  remove  a  delta. 

FILES 

x-file  (see  d€lta{l)) 

z-file  (see  de//a(l)) 

SEE  ALSO 

sccs(l),  delta(l),  get(l),  help(l),  prs(l),  sccsfile(5). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation, 

DIAGNOSTICS 

Use  help{l)  for  explanations. 
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NAME 

rmdir,  rm  —  remove  (unlink)  directories  or  files 

SYNOPSIS 

rmdir  dir  ... 

rm  1  -f  1  [  -r  ]  [  -I  I  1  -  1  file  ... 

DESCRIPTION 

Rmdir  removes  entries  for  the  named  directories,  which  must  be  empty. 

Rm  removes  the  entries  for  one  or  more  files  from  a  directory.  If  an  entry  was  the  last  link  to 
the  file,  the  file  is  destroyed.  Removal  of  a  file  requires  write  permission  in  its  directory,  but  nei- 
ther  read  nor  write  permission  on  the  file  itself. 

If  a  file  has  no  write  permission  and  the  standard  input  is  a  terminal,  its  permissions  are  printed 
and  a  line  is  read  from  the  standard  input.  If  that  line  begins  with  *y*  the  file  is  deleted,  other¬ 
wise  the  file  remains.  No  questions  are  asked  and  no  errors  are  reported  when  the  — f  (force) 
option  is  given. 

If  a  designated  file  is  a  directory,  an  error  comment  is  printed  unless  the  optional  argument  — r 
has  been  used.  In  that  case,  rm  recursively  deletes  the  entire  contents  of  the  specified  directory, 
and  the  directory  itself. 

If  the  — i  (interactive)  option  is  in  effect,  rm  asks  whether  to  delete  each  file,  and,  under  — r, 
whether  to  examine  each  directory. 

The  null  option  —  indicates  that  all  the  arguments  following  it  are  to  be  treated  as  file  names. 
This  allows  the  specification  of  file  names  starting  with  a  minus. 

SEE  ALSO 

rm(l),  unlink(2),  rmdir(2) 
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NAME 

rsh  —  remote  shell 
SYNOPSIS 

rsh  host  I  —I  username  1  1  — n  |  command 

host  [  —1  username  ]  |  — n  [  command 
DESCRIPTION 

Rsh  connects  to  the  specified  host,  and  executes  the  specified  command.  Rsh  copies  its  standard 
input  to  the  remote  command,  the  standard  output  of  the  remote  command  to  its  standard  out¬ 
put,  and  the  standard  error  of  the  remote  command  to  its  standard  error.  Interrupt,  quit  and 
terminate  signals  are  propagated  to  the  remote  command;  rsh  normally  terminates  when  the 
remote  command  does. 

If  you  omit  command,  instead  of  executing  a  single  command,  rsh  logs  you  in  on  the  remote  host 
using  r/oytn(lC). 

Shell  metacharacters  which  are  not  quoted  are  interpreted  on  the  local  machine,  while  quoted 
metacharacters  are  interpreted  on  the  remote  machine.  Thus  the  command: 

tutorial%  rsh  lizard  cat  llzard»flle  »  tutorial.fl!c 
appends  the  remote  file  lizard.file  from  the  machine  called  lizard  to  the  file  called  tutorial.file  on 
the  machine  called  tutorial,  while  the  command: 

tutorial^  rsh  lizard  cat  tlzard.flle  "»*  another .llzard.flle 
appends  the  file  lizard.file  on  the  machine  called  lizard  to  the  file  another.lizard.file.  which  also 
resides  on  the  machine  called  lizard. 

Host  names  are  given  in  the  file  /etc/hosts.  Each  host  has  one  standard  name  (the  first  name 
given  in  the  file),  which  is  rather  long  and  unambiguous,  and  optionally  one  or  more  nicknames. 
The  host  names  for  local  machines  are  also  commands  in  the  directory  /usr/hosts;  if  you  put  this 
directory  in  your  search  path  then  the  rsh  can  be  omitted. 

OPTIONS 

—1  username 

use  username  as  the  remote  username  instead  of  your  local  username.  In  the  absence  of 
this  option,  the  remote  username  is  the  same  as  your  local  username.  This  remote  name 
must  be  equivalent  (in  the  sense  of  rlogin{lC))  to  the  originating  account;  no  provision  is 
made  for  specifying  a  password  with  a  command. 

— n  redirect  the  input  of  rsh  to  /dev/null.  You  need  this  option  if  you  are  using  caA(l)  and 

put  a  rsh{lC)  in  the  background  without  redirecting  its  input  away  from  the  terminal 
because  it  will  block  even  if  no  reads  are  posted  by  the  remote  command. 

The  type  of  remote  shell  (sh  or  esh)  is  determined  by  the  user’s  entry  in  the  file  /etc/passwd  on 
the  remote  system. 

FILES 

/etc/hosts 

/usr/hosts/* 

SEE  ALSO 

rlogin(lC) 

BUGS 

You  cannot  run  an  interactive  command  (like  t;t(l));  use  r/oy»rt(lC). 

Stop  signals  stop  the  local  rsh  process  only;  this  is  arguably  wrong,  but  currently  hard  to  fix  for 
reasons  too  complicated  to  explain  here. 
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The  current  local  environment  is  not  passed  to  the  remote  shell. 
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NAME 

ruptime  —  show  host  status  of  local  machines 
SYNOPSIS 

ruptime  [  —a  ]  |  “I  j  [  “t  ]  (  — u  ] 

DESCRIPTION 

Ruptime  gives  a  status  line  like  uptime  for  each  machine  on  the  local  network;  these  are  formed 
from  packets  broadcast  by  each  host  on  the  network  once  a  minute. 

Machines  for  which  no  status  report  has  been  received  for  5  minutes  are  shown  as  being  down. 

Normally,  the  listing  is  sorted  by  host  name,  but  this  order  can  be  changed  by  specifying  one  of 
the  options  listed  below. 

OPTIONS 

—a 

count  even  those  users  who  have  been  idle  for  an  hour  or  more. 

—1  sort  the  display  by  load  average. 

-t 

sort  the  display  by  up  time, 

— u 

sort  the  display  by  number  of  users. 

FILES 

/usr/spool/rwho/whod.*  data  files 

SEE  ALSO 

rwho(lC) 
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NAME 

rwall  —  write  to  all  users  over  a  network 

SYNOPSIS 

rwall  hostl  host2 

rwall  “*n  netgroupl  netgroup2 

rwall  — h  host  — n  netgroup 

DESCRIPTION 

Rwall  reads  a  message  from  standard  input  until  end-of-file.  It  then  sends  this  message,  preceded 
by  the  line  ‘^Broadcast  Message  to  all  users  logged  in  on  the  specified  host  machines.  With 
the  -n  option,  it  sends  to  the  specified  network  groups,  which  are  defined  in  netgroup{b). 

A  machine  can  only  receive  such  a  message  if  it  is  running  ru;a/W(8),  which  is  normally  started  up 
from  /etc/ servers  by  the  daemon  me(d(8). 

FILES 

/etc/servers 
SEE  ALSO 

wall(l),  netgroup(S),  rwal!d(8),  shutdown(8) 
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NAME 

rwho  —  who’s  logged  in  on  local  machines 

SYNOPSIS 

rwho  [  —a  ] 

DESCRIPTION 

The  rwho  command  produces  output  similar  to  «;Ao(l),  but  for  all  machines  on  your  network.  If 
no  report  has  been  received  from  a  machine  for  5  minutes,  rwho  assumes  the  machine  is  down, 
and  does  not  report  users  last  known  to  be  logged  into  that  machine. 

If  a  user  hasn’t  typed  to  the  system  for  a  minute  or  more,  rwho  reports  this  idle  time.  If  a  user 
hasn’t  typed  to  the  system  for  an  hour  or  more,  the  user  is  omitted  from  the  output  of  rwho 
unless  the  —a  flag  is  given. 

OPTIONS 

—a  report  all  users  whether  or  not  they  have  typed  to  the  system  in  the  past  hour. 

FILES 

/usr/spool/rwho/whod.^  Information  about  other  machines 

SEE  ALSO 

ruptime(lC),  rwhod(8C) 

BUGS 

Does  not  work  through  gateways. 

This  is  unwieldy  when  the  number  of  machines  on  the  local  net  is  large. 
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NAME 

sact  -  print  current  SCCS  file  editing  activity 

SYNOPSIS 

/uBr/sccB/sact  file 

DESCRIPTION 

Sact  informs  the  user  of  any  SCCS  files  which  have  had  one  or  more  get  — e  commands  applied 
to  them,  that  is,  there  are  files  out  for  editing,  and  deltas  are  pending.  If  a  directory  is  named  on 
the  command  line,  sad  behaves  as  though  each  file  in  the  directory  were  specified  as  a  named 
file,  except  that  non-SCCS  files  and  unreadable  files  are  silently  ignored.  If  a  name  of  —  is  given, 
the  standard  input  is  read  with  each  line  being  taken  as  the  name  of  an  SCCS  file  to  be  processed. 
The  output  for  each  named  file  consists  of  five  fields  separated  by  spaces. 

Field  1  specifies  the  SID  of  a  delta  that  currently  exists  in  the  SCCS  file  to  which 
changes  will  be  made  to  make  the  new  delta. 

Field  2  specifies  the  SID  for  the  new  delta  to  be  created. 

Field  3  contains  the  logname  of  the  user  who  will  make  the  delta  (that  is,  executed  a 

get  for  editing). 

Field  4  contains  the  date  that  get  — e  was  executed. 

Field  5  contains  the  time  that  get  — *e  was  executed, 

SEE  ALSO 

sccs(l),  delta(l),  get(l),  unget(l). 

Source  Code  Control  System  lu.  Programming  Tools  for  the  Sun  Workstation, 

DIAGNOSTICS 

Use  kelp{l)  for  explanations. 
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NAME 

sees  —  front  end  for  the  sees  subsystem 
SYNOPSIS 

sees  I  — ^  j  [  —Aprefixpaih  ]  [  —pfinalpatk  \  command  (  SCCS-flags  [  file  •.,  ] 

DESCRIPTION 

system**  The  sees  command  is  a  front  end  to  the  utility  programs  of  the  Source  Code  Control 
System  (sees),  which  helps  them  mesh  more  cleanly  with  the  rest  of  UNIX.  Sees  runs  the  com¬ 
mand  with  the  specified  SCeS-flags  and  files. 

Note  that  sees  normally  prefixes  each  file,  or  the  last  component  of  each  file,  with  the  string 
SCCS/e*,  because  you  normally  keep  your  SCCS  database  files  in  a  directory  called  SCeS,  and 
each  database  file  starts  with  an  a*  prefix. 

Sees  program  options  must  appear  before  the  command  argument.  Flags  to  be  passed  to  the 
actual  SCCS  utility  program  must  appear  after  the  command  argument.  These  flags  are  specific 
to  the  command  being  used,  and  are  discussed  in  the  manual  page  for  that  command. 

Scc8  also  includes  the  capability  to  run  *set  user  id’  to  another  user  to  provide  additional  protec¬ 
tion.  Certain  commands  (such  as  admin)  cannot  be  run  ‘set  user  id’  by  all  users,  since  this  would 
allow  anyone  to  change  the  authorizations.  Such  commands  are  always  run  as  the  real  user. 

OPTIONS 

— r  Runs  sees  as  the  real  user  rather  than  as  whatever  effective  user  sees  is  ‘set  user  id’  to. 
—dprefixpath 

Defines  the  prefix  portion  of  the  pathname  for  the  SCCS  database  files.  The  default 
prefix  portion  of  the  pathname  is  the  current  directory.  Prefizpath  is  prefixed  to  the 
entire  pathname.  For  example: 

tutorial%  aces  — d/uar/lnclude  get  sya/lnode.h 
converts  to: 

get  /usr/IncIude/sys/SCCS/s.inode.h 

The  intent  here  is  to  create  aliases  such  as: 

alias  syssccs  sees  — d/usr/sre 

which  will  be  used  as: 

tutorial%  syssccs  get  cmd/who.c 

—pfinalpath 

Defines  the  name  of  a  lower  directory  in  which  the  SCCS  files  will  be  found;  SCCS  is  the 
default.  Finalpath  is  appended  before  the  final  component  of  the  pathname.  For  exam¬ 
ple: 

tutorial%  sees  — pprlvate  get  usr/lnclude/stdlo.h 

converts  to: 

get  usr/includc/prlvate/s*stdio.h 

ADDITIONAL  SCCS  COMMANDS 

Several  ‘pseudo-commands’  are  available  in  addition  to  the  usual  SCCS  commands.  These  are: 

admin  The  admin  command  is  similar  to  that  of  the  raw  SCCS  admin  command.  When  creating 
new  8*  files,  the  create  command  (described  just  below)  does  more  of  the  startup  work 
for  you  and  should  be  used  in  preference  to  admin. 

create  Create  is  used  when  creating  new  8.  files.  Given  a  C  source  language  file  called 
ohscure.c,  Create  does  the  following  actions:  (1)  creates  the  8.  file  called  e.obscure^c  in 
the  SCCS  directory;  (2)  renames  the  original  source  file  to  ^ohscure.c;  (3)  does  an  sees 
get  on  ohscuremc. 

edit  Get  a  file  for  editing. 

delget  Perform  a  delta  on  the  named  files  and  then  get  new  versions.  The  new  versions  have  id 
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keywords  expanded,  and  so  cannot  be  edited. 

ddedii  Same  as  delget,  but  produces  new  versions  suitable  for  editing.  Deledit  is  useful  for  mak< 
ing  a  ‘checkpoint*  of  your  current  editing  phase. 

fix  Removes  the  named  delta,  but  leaves  you  with  a  copy  of  the  delta  with  the  changes  that 
were  in  it.  Fix  must  be  followed  by  a  — r  flag.  Fix  is  useful  for  fixing  small  compiler 
bugs,  etc.  Since  fix  doesn’t  leave  audit  trails,  use  it  carefully. 

clean  Removes  everything  from  the  current  directory  that  can  be  recreated  from  SCCS  files. 
Clean  checks  for  and  does  not  remove  any  files  being  edited.  If  Clean  — b  is  used, 
branches  are  not  checked  to  see  if  they  are  currently  being  edited.  Note  that  —b  is 
dangerous  if  you  are  keeping  the  branches  in  the  same  directory, 

unedit  ‘Undoes’  the  last  edit  or  get  — e  and  returns  a  file  to  its  previous  condition.  If  you  unedit 
a  file  being  edited,  all  changes  made  since  the  beginning  of  the  editing  session  are  lost. 

info  Displays  a  list  of  all  files  being  edited.  If  the  — b  flag  is  given,  branches  (that  is,  SID’s 
with  two  or  fewer  components)  are  ignored.  If  the  — u  flag  is  given  (with  an  optional 
argument),  only  files  being  edited  by  you  (or  the  named  user)  are  listed. 

check  Checks  for  files  currently  being  edited,  like  info,  but  returns  an  exit  code  rather  than  a 
listing:  nothing  is  printed  if  nothing  is  being  edited,  and  a  non-zero  exit  status  Is 
returned  if  anything  is  being  edited.  Check  may  thus  be  included  in  an  ‘install’  entry  in  a 
makefile,  to  ensure  that  everything  is  included  in  an  SCCS  file  before  a  version  is 
installed. 

tell  Displays  a  list  of  files  being  edited  on  the  standard  output.  Filenames  are  separated  by 
newlines.  Takes  the  — b  and  — u  flags  like  info  and  check. 

diffe  Compares  (in  diff-like  format)  the  current  version  of  the  program  you  have  out  for  edit¬ 
ing  and  the  versions  in  SCCS  format. 

EXAMPLES 

To  put  a  file  called  myprogram^c  into  SCCS  format  for  the  first  time,  assuming  also  that  there  is 
no  SCCS  directory  already  existing: 

tutorial%  mkdir  SCCS 
tutoriat%  sees  create  myprogram.e 

myprogram.c: 

1.1 

14  lines 

after  you  have  verified  that  everything  is  all  right 
you  remove  the  version  of  the  file  that  starts  with  a  comma: 
tutorial%  rm  iinyprogram.e 
tutorial% 

To  get  a  copy  of  myprogram.c  for  editing,  edit  that  file,  then  place  it  back  in  the  SCCS  database: 

tutorial%  sees  edit  myprogram.c 

1.1 

new  delta  1.2 
14  lines 

tutorial%  vl  myprogram.c 
your  editing  session 
tutorial%  sees  delget  myprogram.c 

comments?  Added  abusive  responses  for  compatibility  with  rest  of  system 

1.2 

7  inserted 
7  deleted 
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7  unchanged 

1.2 

14  lines 
tutorial% 

To  get  z  file  from  another  directory: 

tutorial%  sccc  — p/uif/wc/bcc*/  get  cc.c 

or: 

tutoriaI%  »ccs  get  /uBr/sre/scctf/ce.e 

To  make  a  delta  of  a  large  number  of  files  in  the  current  directory: 
tutorial%  sees  delta 

To  get  a  list  of  files  being  edited  that  are  not  on  branches: 

tutoriaI%  sees  info  — b 
To  delta  everything  that  you  are  editing: 

tutorial%  sees  delta  'sccb  tell  — u' 

In  a  makefile,  to  get  source  files  from  an  SCCS  file  if  it  does  not  already  exist: 

SRCS  =*  <list  of  source  files> 

$(SRCS): 

sees  get  $(REL)  $@ 

REGULAR  SCCS  COMMANDS 

The  ‘regular*  SCCS  commands  are  described  very  briefly  below.  It  is  unlikely  that  you  ever  need 
to  use  these  commands  because  the  user  interface  is  so  complicated,  and  the  $cc8  front  end  com- 
mand  does  99.9%  of  the  interesting  tasks  for  you. 

admin  Creates  new  SCCS  files  and  changes  parameters  of  exitsing  SCCS  files.  You  can  use 
BCCB  create  to  create  new  SCCS  files,  or  use  bccb  admin  to  do  other  things. 

ede  Changes  the  commentary  material  in  an  SCCS  delta. 

comb  Combines  SCCS  deltas  and  reconstructs  the  SCCS  files. 

delta  Permanently  introduces  changes  that  were  made  to  a  file  -previously  retrieved  via 
sees  get.  You  can  use  sees  delget  as  the  more  useful  version  of  this  command  since 
BCCB  delget  does  all  of  the  useful  work  and  more  to  boot. 

get  Extracts  a  file  from  the  SCCS  database,  either  for  compilation,  or  for  editing  when  the 
— c  option  is  used.  Use  bccb  get  if  you  really  need  it,  but  bccb  delget  will  normally 
have  done  this  job  for  you.  Use  bccb  edit  instead  of  get  with  the  —e  option. 

help  Supposed  to  help  you  interpret  SCCS  error  messages,  but  usually  just  parrots  the  mes- 
saage  and  is  generally  not  considered  very  helpful. 

prs  Displays  information  about  what  is  happening  in  an  SCCS  file. 

rmdel  Removes  a  delta  from  an  SCCS  file. 

sad  Displays  information  about  editing  activity  in  an  SCCS  file.  The  bccb  Info  command  is  a 
lot  more  useful  for  the  real  life  user. 

eccediff  Compares  two  versions  of  an  SCCS  file  and  generates  the  differences  between  the  two 
versions.  The  bccb  delget  command  docs  all  this  work  as  part  of  its  normal  process. 

unget  Undoes  the  work  of  a  previous  get  —e  command  or  a  bccb  edit  command.  Use  the 
BCCB  unedit  command  as  a  useful  alternative. 

val  Determines  if  a  given  SCCS  file  meets  specified  criteria.  If  you  use  the  eccs  command, 
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you  shouldn’t  need  to  use  vat,  because  its  user  interface  is  unbelievable. 
what  Displays  SCCS  identification  information. 

SEE  ALSO 

admin(l),  comb(l),  cdc(l),  delta(l),  get(l),  help(l),  prs(l),  rmdel(l),  sact(l),  sccsdifr(l),  sccsfile(5), 
unget(l),  val(l),  what(l) 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 
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NAME 

sccsdiff  —  compare  two  versions  of  an  SCCS  file 
SYNOPSIS 

/uar/accB/BccBdlff  — rS/Df  —tSID2  |  — p  |  (  — bh  |  files 
DESCRIPTION 

Sccsdiff  compares  two  versions  of  an  SCCS  file  and  generates  the  differences  between  the  two  ver* 
sions.  Any  number  of  SCCS  files  may  be  specified,  but  options  apply  to  all  files. 

OPTIONS 

—rSID?  SIDl  and  SID2  specify  the  deltas  of  an  SCCS  file  that  are  to  be  compared.  Versions 
are  passed  to  dt^(l)  in  the  order  given. 

— p  pipe  output  for  each  file  through  pr(l). 

—an  n  is  the  file  segment  size  that  diff  will  use.  This  is  useful  when  the  system  load  is 

high. 

FILES 

/tmp/get?????  Temporary  files 
SEE  ALSO 

sccs(l),  diff(l),  get(l),  help(l),  pr(l). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 

DIAGNOSTICS 

“file:  No  differences”  If  the  two  versions  are  the  same. 

Use  Ae/p(l)  for  explanations. 
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NAME 

screendump  —  dump  frame  buffer  image 
SYNOPSIS 

screendump  |  — f  display  ]  [  — e  ]  |  — t  type  |  [  output-file  j 
DESCRIPTION 

Screendump  reads  out  the  contents  of  a  frame  buffer  on  any  model  of  Sun  Workstation  and  out¬ 
puts  the  display  image  in  Sun  standard  rasterfile  format  (see  ( usrf include/ raster fileM)  on 
output-file  (or  on  the  standard  output  if  output-file  is  not  specified). 

By  default,  screendump  attempts  to  output  the  contents  of  the  console  frame  buffer  [/dev/fb). 
The  — f  option  explicitly  sets  the  name  of  the  desired  frame  buffer  device. 

The  utility  program  screenload  displays  Sun  standard  rasterfiles  on  an  appropriate  Sun  Worksta¬ 
tion  monitor.  Output  filters  exist  for  printing  standard  monochrome  rasterfiles  on  Versatec  V-80 
electrostatic  plotters. 

OPTIONS 

— f  display 

Use  display  as  the  device  name  of  the  display, 

-e  Shorthand  for  — t  2. 

— t  type 

Specify  the  type  of  the  rasterfile  to  write: 

0  Old  format  files  compatible  with  Release  1.1  software. 

1  Standard  format. 

2  Run-length  encoding  of  bytes. 

65535  To  experiment  with  private  encodings. 

EXAMPLES 

tutorial%  screendump  >8ave,thl8.image 

writes  the  current  contents  of  the  console  frame  buffer  into  the  file  saveJhisAmage, 
tutorial%  screendump  — f  /dev/cgoneO  >8ave*color«image 
writes  the  current  contents  of  the  frame  buffer  / dev/ cgoneO  into  the  file  save,colorJmage. 
tutorial%  screendump  |  Ipr  — Pversatec  — v 

sends  a  rasterfile  containing  the  current  frame  buffer  to  the  lineprinter,  selecting  the  printer 
named  ^^versatec'*  and  the  “v'*  output  filter  (see  /etc/printcap). 

FILES 

/dev/fb  Default  name  of  console  display  frame  buffer. 

/dev/cgoneO  Default  name  of  the  Sun-1  color  display  frame  buffer. 

/dev/cgtwoO  Default  name  of  the  Sun-2  color  display  frame  buffer. 

/usr/lib/rasfilters/*  Filters  for  the  raster  file 

SEE  ALSO 

screenload(l),  Ipr(l) 

pr^dump  in  Programmer's  Reference  Manual  for  SunWindows 
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NAME 

screenload  —  restore  frame  buffer  image 
SYNOPSIS 

Bcreenload  [  -d  |  [  -f  display  [  [  -lindex  ]  (  -b  [  [  -g  ]  [  -p  ]  [  -w  j  [  -h#  [####  [...1|]  I 
input-file  ] 

DESCRIPTION 

Screenload  accepts  input  in  Sun  standard  rasterfile  format  (see  lusrf  include/ raster  file. h)  and 
attempts  to  display  the  input  on  the  appropriate  monitor  (monochrome  or  color).  Screenload 
normally  displays  rasterftles  on  the  console  display,  but  displays  them  on  some  heuristically  deter¬ 
mined  color  display  if  it  finds  no  console  display.  Screenload  displays  color  rasterfiles  only  on  a 
color  monitor.  Screenload  is  able  to  display  monochrome  rasters  on  a  color  display. 

If  the  dimensions  of  the  image  contained  in  the  input  data  are  smaller  than  the  actual  resolution 
of  the  display  (for  example,  loading  a  1024-by-800  Sun-1  image  on  a  1152-by-900  Sun-2  display), 
screenload  centers  the  image  on  the  actual  workstation  screen  and  fills  the  border  area  with  solid 
black  (by  default).  Various  options  may  be  used  to  change  the  fill  pattern. 

If  the  dimensions  of  the  image  contained  in  the  input  data  are  larger  than  the  actual  resolution 
of  the  display,  screenload  clips  the  right  and  bottom  edges  of  the  input  image. 

If  there  is  an  optional  filename  argument,  screenload  reads  its  input  data  from  that  file.  If  no 
filename  argument  is  given,  screenload  reads  its  input  data  from  the  standard  Input. 

The  utility  program  screendump  creates  Sun  standard  rasterfiles  from  the  display  on  a  Sun 
Workstation  monitor. 

OPTIONS 

— d  Verify  that  display  dimensions  and  input  data  Image  dimensions  match,  and  print  warn¬ 

ing  messages  if  they  do  not. 

—f  display 

Use  display  as  the  name  of  the  frame  buffer  device. 

—\index 

If  the  image  is  smaller  than  the  display,  use  index  (0  <—  index  <  256)  as  the  index  value 
into  the  color  map  for  the  foreground  color  of  the  border  fill  pattern.  The  default  index 
value  is  255. 

If  the  input  data  dimensions  are  smaller  than  the  display  dimensions,  fill  the  border  with 
a  pattern  of  solid  ones  {default).  On  a  monochrome  display  this  results  in  a  black  border; 
on  a  color  display  the  color  map  value  selected  by  the  —I  option  determines  the  border 
color. 

If  the  input  data  dimensions  are  smaller  than  the  display  dimensions,  fill  the  border  with 
a  pattern  of  “desktop  grey”.  On  a  monochrome  display  this  results  in  a  border  matching 
the  background  pattern  used  by  the  SunWindows  system;  on  a  color  display  the  color 
map  value  selected  by  the  —I  option  determines  the  foreground  border  color,  though  the 
pattern  is  the  same  as  on  a  monochrome  display. 

Wait  for  a  newline  to  be  typed  on  the  standard  input  before  exiting. 

If  the  input  data  dimensions  are  smaller  than  the  display  dimensions,  fill  the  border  with 
a  pattern  of  solid  zeros.  On  a  monochrome  display  this  results  in  a  white  border;  on  a 
color  display  the  color  map  value  at  index  0  determines  the  border  color. 

If  the  Input  data  dimensions  are  smaller  than  the  display  dimensions,  fill  the  border  with 
the  bit  pattern  described  by  the  following  #  16-bit  hexadecimal  constants.  Note  that  a 
“1”  bit  is  black  and  a  “0”  bit  is  white  on  the  monochrome  display;  on  a  color  diplay  the 
color  map  value  selected  by  the  —1  option  determines  the  border  foreground  color.  The 
number  of  hex  constants  in  the  pattern  is  limited  to  16. 
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EXAMPLES 

tutoria]%  tereenload  8aved.dlBplay .Image 

reloads  the  raster  image  contained  in  the  file  eaved.display.image  on  the  display  type  indicated  by 
the  rasterfile  header  in  that  file. 


tutorial^  aereenload  — f/dev/egoneO  monoehrome.tmage 


reloads  the  raster  image  in  the  file  monochrome.itnage  on  the  frame  buffer  device  /dev/egoneO. 
tutorial^  screenload  —hi  fflT  sun_l.saved.tmage 


is  equivalent  to  the  — b  option  (fill  border  with  black),  while 

tutorial%  aereenload  — h4  8888  8888  2222  2222  aun_l.saved.lmage 


is  equivalent  to  the  — g  option  (fill  border  with  desktop  grey). 


FILES 

/dev/fb 

/dev/cgoneO 

/dev/cgtwoO 

/usr/lib/rasfilters/* 


Default  name  of  console  display  frame  buffer 
Default  name  of  Sun-1  color  display  frame  buffer 
Default  name  of  the  Sun-2  color  display  frame  buffer. 
Filters  for  the  raster  file 


SEE  ALSO 

screendump(l) 

prjoad  in  Programmer’s  Reference  Manual  for  SunWindows 
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NAME 

script  —  make  typescript  of  terminal  session 

SYNOPSIS 

script  [  —a  j  |  file  ] 

DESCRIPTION 

Script  makes  a  typescript  of  everything  printed  on  your  terminal.  The  typescript  is  written  to 
file,  or  appended  to  file  if  the  —a  option  is  given.  It  can  be  sent  to  the  line  printer  later  with  Ipr. 
If  no  file  name  is  given,  the  typescript  is  saved  in  the  file  typescript. 

The  script  ends  when  the  forked  shell  exits. 


OPTIONS 

Append  the  script  to  the  specified  file  instead  of  writing  over  it. 


BUGS 

Script  places  everything  in  the  log  file.  This  is  not  what  the  naive  user  expects. 
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NAME 

sed  —  stream  editor 
SYNOPSIS 

sed  I  — n  I  I  — e  script  |  [  — f  sjile  ]  [file  ] ... 

DESCRIPTION 

Sed  copies  the  named  files  (standard  input  default)  to  the  standard  output,  edited  according  to  a 
script  of  commands. 

OPTIONS 

— e  Is  a  list  of  edit  commands  for  serf.  If  there  is  just  one  — e  option  and  no  — fs,  the  — e  flag 

— e  may  be  omitted. 

— f  Take  the  script  from  sfiU 

— n  suppress  the  default  output. 

SED  SCRIPTS 

sed  scripts  consist  of  editing  commands,  one  per  line,  of  the  following  form: 

[address  [,  address]  j  function  [arguments] 

In  normal  operation  serf  cyclically  copies  a  line  of  input  into  a  pattern  space  (unless  there  is  some¬ 
thing  left  after  a  ‘D’  command),  applies  in  sequence  all  commands  whose  addresses  select  that 
pattern  space,  and  at  the  end  of  the  script  copies  the  pattern  space  to  the  standard  output 
(except  under  — n)  and  deletes  the  pattern  space. 

An  address  is  either  a  decimal  number  that  counts  input  lines  cumulatively  across  files,  a  '$’  that 
addresses  the  last  line  of  input,  or  a  context  address,  ‘/regular  expression/’,  in  the  style  of  erf(l) 
modified  thus; 

The  escape  sequence  ‘\n'  matches  a  newline  embedded  in  the  pattern  space. 

A  command  line  with  no  addresses  selects  every  pattern  space. 

A  command  line  with  one  address  selects  each  pattern  space  that  matches  the  address. 

A  command  line  with  two  addresses  selects  the  inclusive  range  from  the  first  pattern  space  that 
matches  the  first  address  through  the  next  pattern  space  that  matches  the  second.  If  the  second 
address  is  a  number  less  than  or  equal  to  the  line  number  first  selected,  only  one  line  is  selected. 
Thereafter  the  process  is  repeated,  looking  again  for  the  first  address. 

Editing  commands  can  be  applied  only  to  non-selected  pattern  spaces  by  use  of  the  negation  func¬ 
tion  “!’  (below). 

In  the  following  list  of  functions  the  maximum  number  of  permissible  addresses  for  each  function 
is  indicated  in  parentheses. 

An  argument  denoted  text  consists  of  one  or  more  lines,  all  but  the  last  of  which  end  with  ‘\’  to 
hide  the  newline.  Backslashes  in  text  are  treated  like  backslashes  in  the  replacement  string  of  an 
‘s’  command,  and  may  be  used  to  protect  initial  blanks  and  tabs  against  the  stripping  that  is 
done  on  every  script  line. 

An  argument  denoted  rfile  or  wfite  must  terminate  the  command  line  and  must  be  preceded  by 
exactly  one  blank.  Each  wfite  is  created  before  processing  begins.  There  can  be  at  most  10  dis¬ 
tinct  wfile  arguments. 

(1) a\ 

text 

Append:  Place  text  on  the  output  before  reading  the  next  input  line. 

(2) b  label 

Branch  to  the  command  bearing  the  label.  Branch  to  the  end  of  the  script  if  label  is 
empty. 
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(2)c\ 

text 

Change:  Delete  the  pattern  space.  With  0  or  1  address  or  at  the  end  of  a  2-address 
range,  place  text  on  the  output.  Start  the  next  cycle. 

(2)  d  Delete  the  pattern  space.  Start  the  next  cycle. 

(2)D  Delete  the  initial  segment  of  the  pattern  space  through  the  first  newline.  Start  the  next 

cycle. 

(2)  g  Replace  the  contents  of  the  pattern  space  by  the  contents  of  the  hold  space. 

(2)G  Append  the  contents  of  the  hold  space  to  the  pattern  space. 

(2)h  Replace  the  contents  of  the  hold  space  by  the  contents  of  the  pattern  space. 

(2)H  Append  the  contents  of  the  pattern  space  to  the  hold  space. 

(1) i\ 

text 

Insert:  Place  text  on  the  standard  output. 

(2) n  Copy  the  pattern  space  to  the  standard  output.  Replace  the  pattern  space  with  the  next 

line  of  input. 

(2)N  Append  the  next  line  of  input  to  the  pattern  space  with  an  embedded  newline.  (The 
current  line  number  changes.) 

(2)p  Print:  Copy  the  pattern  space  to  the  standard  output. 

(2)P  Copy  the  initial  segment  of  the  pattern  space  through  the  first  newline  to  the  standard 

output. 

(1) q  Quit:  Branch  to  the  end  of  the  script.  Do  not  start  a  new  cycle. 

(2) r  rfile 

Read  the  contents  of  rfile.  Place  them  on  the  output  before  reading  the  next  input  line. 
(2)  s/ regular  expression/ replacement/ flags 

Substitute  the  replacement  string  for  instances  of  the  regular  expression  in  the  pattern 
space.  Any  character  may  be  used  instead  of  */*.  For  a  fuller  description  see  ed(l). 
Flags  is  zero  or  more  of 

g  Global:  Substitute  for  all  nonoverlapping  instances  of  the  regular  expression 

rather  than  just  the  first  one. 

p  Print  the  pattern  space  if  a  replacement  was  made, 
w  wfile  Write:  Append  the  pattern  space  to  wfile  if  a  replacement  was  made. 

(2)t  label 

Test:  Branch  to  the  command  bearing  the  label  if  any  substitutions  have  been  made 
since  the  most  recent  reading  of  an  input  line  or  execution  of  a  V.  If  label  is  empty, 
branch  to  the  end  of  the  script. 

(2)w  wfile 

Write:  Append  the  pattern  space  to  wfile. 

(2)x  Exchange  the  contents  of  the  pattern  and  hold  spaces. 

{2)y/ stringl/stringS/ 

Transform:  Replace  all  occurrences  of  characters  in  stringl  with  the  corresponding  char¬ 
acter  in  strings.  The  lengths  of  stringl  and  strings  must  be  equal. 

(2)!  function 

Don’t:  Apply  the  function  (or  group,  if  function  is  *{’)  only  to  lines  not  selected  by  the 
address(es). 
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(0):  label 

This  command  docs  nothing;  it  bears  a  label  for  ‘b’  and  ‘t’  commands  to  branch  to.  Note 
that  the  maximum  length  of  label  is  seven  characters. 

(1) =  Place  the  current  line  number  on  the  standard  output  as  a  line. 

(2)  {  Execute  the  following  commands  through  a  matching  only  when  the  pattern  space  is 

selected. 

(0)  An  empty  command  is  ignored. 

SEE  ALSO 

ed(l),  grep(l),  awk(l),  lex(l) 

Using  sed,  the  Stream  Text  Editor  in  Editing  and  Text  Processing  on  the  Sun  Workstation. 
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NAME 

sh,  for,  case,  if,  while,  *,  break,  continue,  cd,  eval,  exec,  exit,  export,  login,  newgrp,  read, 
readonly,  set,  shift,  times,  trap,  umask,  wait  —  command  language 

SYNOPSIS 

sh  I  — celknrstuvx  )  [  arg  |  . . . 

DESCRIPTION 

Sh  is  a  command  programming  language  that  executes  commands  read  from  a  terminal  or  a  file. 
See  invocation  for  the  meaning  of  arguments  to  the  shell. 

Commands. 

A  simple-command  is  a  sequence  of  non  blank  words  separated  by  blanks  (a  blank  is  a  tab  or  a 
space).  The  first  word  specifies  the  name  of  the  command  to  be  executed.  Except  as  specified 
below  the  remaining  words  are  passed  as  arguments  to  the  invoked  command.  The  command 
name  is  passed  as  argument  0  (see  txtcvt{2)).  The  value  of  a  simple-command  is  its  exit  status  if 
it  terminates  normally  or  200-f-afaiua  if  it  terminates  abnormally  (see  sigvec[2)  for  a  list  of  status 
values), 

A  pipeline  is  a  sequence  of  one  or  more  commands  separated  by  I  The  standard  output  of  each 
command  but  the  last  is  connected  by  a  pipe{2)  to  the  standard  input  of  the  next  command. 
Each  command  is  run  as  a  separate  process;  the  shell  waits  for  the  last  command  to  terminate. 

A  list  is  a  sequence  of  one  or  more  pipelines  separated  by  ;,  &,  &&  or  II  and  optionally  ter¬ 
minated  by  ;  or  &.  ;  and  &  have  equal  precedence  which  is  lower  than  that  of  &&  and  II;  && 
and  1 1  also  have  equal  precedence.  A  semicolon  causes  sequential  execution;  an  ampersand  causes 
the  preceding  pipeline  to  be  executed  without  waiting  for  it  to  finish.  The  symbol  &&  causes  the 
list  following  to  be  executed  only  if  the  preceding  pipeline  returns  a  zero  value.  The  symbol  11 
causes  the  list  following  to  be  executed  only  if  the  preceding  pipeline  returns  a  non  zero  value. 
Newlines  may  appear  in  a  list^  instead  of  semicolons,  to  delimit  commands. 

A  command  is  either  a  simple-command  or  one  of  the  following.  The  value  returned  by  a  com¬ 
mand  is  that  of  the  last  simple-command  executed  in  the  command.  Note  that  many  keywords 
such  as  done  are  only  recognized  when  they  are  the  first  keyword  on  a  line, 
for  name  [  In  word  ] 

do 

list 

done 

Each  time  a  for  command  is  executed  name  is  set  to  the  next  word  in  the  In  word  list.  If 
In  word*.*  is  omitted,  In  is  assumed.  Execution  ends  when  there  are  no  more  words  in  the 
list. 

case  word  In 

pattern  \  \  pattern  ]  «..  )  list  ;;  | 
pattern  [  \  pattern  J  list  | 

esac 

A  case  command  executes  the  list  associated  with  the  first  pattern  that  matches  word.  The  form 
of  the  patterns  is  the  same  as  that  used  for  file  name  generation, 
if  list 
then  list 
[ellf  list 
then  I  . . . 

I  else 
list  ] 
fl 
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The  list  following  If  is  executed  and  if  it  returns  zero  the  list  following  then  is  executed.  Other¬ 
wise,  the  list  following  ellf  is  executed  and  if  its  value  is  zero  the  list  following  then  is  executed. 
Failing  that  the  else  list  is  executed. 

while  list 
I  do 
list  I 
done 

A  while  command  repeatedly  executes  the  while  list  and  if  its  value  is  zero  executes  the  do  list; 
otherwise  the  loop  terminates.  The  value  returned  by  a  while  command  is  that  of  the  last  exe¬ 
cuted  command  in  the  do  list  until  may  be  used  in  place  of  while  to  negate  the  loop  termina¬ 
tion  test. 

(  list  )  Execute  list  in  a  subshell. 

{  list  }  list  is  simply  executed. 

The  following  words  are  only  recognized  as  the  first  word  of  a  command  and  when  not  quoted. 

if  then  else  elif  fl  case  esac  for  while  until  do  done  {  } 

Command  substitution. 

The  standard  output  from  a  command  enclosed  in  a  pair  of  back  quotes  ('  ')  may  be  used  as 
part  or  all  of  a  word;  trailing  newlines  are  removed. 

Parameter  substitution. 

The  character  $  is  used  to  introduce  substitutable  parameters.  Positional  parameters  may  be 
assigned  values  by  set.  Variables  may  be  set  by  writing 

name=value  |  name^value  ]  ... 

$  {parameter} 

A  parameter  is  a  sequence  of  letters,  digits  or  underscores  (a  name),  a  digit,  or  any  of  the 
characters  ♦  @  #  ?  —  $  !•  The  value,  if  any,  of  the  parameter  is  substituted.  The 
braces  are  required  only  when  parameter  is  followed  by  a  letter,  digit,  or  underscore  that 
is  not  to  be  interpreted  as  part  of  its  name.  If  parameter  is  a  digit,  it  is  a  positional 
parameter.  If  parameter  is  »  or  @  then  all  the  positional  parameters,  starting  with  $1, 
are  substituted  separated  by  spaces,  $0  is  set  from  argument  zero  when  the  shell  is 
invoked. 

i  {parameter ---word) 

If  parameter  is  set,  substitute  its  value;  otherwise  substitute  word. 

$  {parameter—  word} 

If  parameter  is  not  set,  set  it  to  word;  the  value  of  the  parameter  is  then  substituted. 
Positional  parameters  may  not  be  assigned  to  in  this  way. 

$  {parameter  f  word} 

If  parameter  is  set,  substitute  its  value;  otherwise,  print  word  and  exit  from  the  shell.  If 
word  is  omitted,  a  standard  message  is  printed. 

$  {parameter'^word} 

If  parameter  is  set,  substitute  otherwise  substitute  nothing. 

In  the  above  word  is  not  evaluated  unless  it  is  to  be  used  as  the  substituted  string.  (So  that,  for 
example,  echo  ${d— 'pwd*"}  will  only  execute  pu;dif  dis  unset.) 

The  following  parameters  are  automatically  set  by  the  shell. 

#  The  number  of  positional  parameters  in  decimal. 

—  Options  supplied  to  the  shell  on  invocation  or  by  set, 

?  The  value  returned  by  the  last  executed  command  in  decimal. 

$  The  process  number  of  this  shell. 
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!  The  process  number  of  the  last  background  command  invoked. 

The  following  parameters  are  used  but  not  set  by  the  shell. 

HOME  The  default  argument  (home  directory)  for  the  cd  command. 

PATH  The  search  path  for  commands  (sec  execution). 

MAIL  If  this  variable  is  set  to  the  name  of  a  mail  file,  the  shell  informs  the  user  of  the 
arrival  of  mail  in  the  specified  file. 

PSl  Primary  prompt  string,  by  default  \ 

PS2  Secondary  prompt  string,  by  default  *> 

IFS  Internal  field  separators,  normally  space,  tab,  and  newline. 

Blank  Interpretation. 

After  parameter  and  command  substitution,  any  results  of  substitution  are  scanned  for  internal 
field  separator  characters  (those  found  in  HFS)  and  split  into  distinct  arguments  where  such 
characters  are  found.  Explicit  null  arguments  (”"  or  ")  are  retained.  Implicit  null  arguments 
(those  resulting  from  parameters  that  have  no  values)  are  removed. 

File  name  generation. 

Following  substitution,  each  command  word  is  scanned  for  the  characters  ♦,  f  and  {.  If  one  of 
these  characters  appears,  the  word  is  regarded  as  a  pattern.  The  word  is  replaced  with  alphabet^ 
ically  sorted  file  names  that  match  the  pattern.  If  no  file  name  is  found  that  matches  the  pat¬ 
tern,  the  word  is  left  unchanged.  The  character  •  at  the  start  of  a  file  name  or  immediately  fol¬ 
lowing  a  /,  and  the  character  /,  must  be  matched  explicitly. 

♦  Matches  any  string,  including  the  null  string, 

f  Matches  any  single  character. 

{*••]  Matches  any  one  of  the  characters  enclosed.  A  pair  of  characters  separated  by  — 
matches  any  character  lexically  between  the  pair. 

Quoting. 

The  following  characters  have  a  special  meaning  to  the  shell  and  cause  termination  of  a  word 
unless  quoted. 

;  &  (  )  I  <  >  newline  Bpace  tab 

A  character  may  be  quoted  by  preceding  it  with  a  backslash  (\)  character,  \newllne  is  ignored. 
All  characters  enclosed  between  a  pair  of  quote  marks  ('  '),  except  a  single  quote,  are  quoted. 
Inside  double  quotes  ("")  parameter  and  command  substitution  occurs  and  \  quotes  the  charac¬ 
ters  backslash  (\),  apostrophe  (*),  double  quote  ("),  and  dollar  sign  ($). 

is  equivalent  to  ”$1  $2  ...”  whereas 
is  equivalent  to  ”$2*^ ... 

Prompting. 

When  used  interactively,  the  shell  prompts  with  the  value  of  PSl  before  reading  a  command.  If 
at  any  time  a  newline  is  typed  and  further  input  is  needed  to  complete  a  command,  the  secon¬ 
dary  prompt  ($PS2)  is  displayed. 

Input  output. 

Before  a  command  is  executed  its  input  and  output  may  be  redirected  using  a  special  notation 
interpreted  by  the  shell.  The  following  may  appear  anywhere  in  a  simple-command  or  may  pre¬ 
cede  or  follow  a  command  and  are  not  passed  on  to  the  invoked  command.  Substitution  occurs 
before  word  or  digit  is  used. 

<word  Use  file  word  as  standard  input  (file  descriptor  0). 

>word  Use  file  word  as  standard  output  (file  descriptor  1).  If  the  file  does  not  exist,  it  is 
created;  otherwise  it  is  truncated  to  zero  length. 

»  word 

Use  file  word  as  standard  output.  If  the  file  exists,  output  is  appended  (by  seeking  to  the 
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end);  otherwise  the  file  is  created. 

«word 

The  shell  input  is  read  up  to  a  line  the  same  as  word,  or  end  of  file.  The  resulting  docu¬ 
ment  becomes  the  standard  input.  If  any  character  of  word  is  quoted,  no  interpretation 
is  placed  upon  the  characters  of  the  document;  otherwise,  parameter  and  command  sub¬ 
stitution  occurs,  \newUne  is  ignored,  and  \  is  used  to  quote  the  characters  backslash 
(\),  dollar  sign  ($),  apostrophe  (’),  and  the  first  character  of  word, 

<&  digit 

The  standard  input  is  duplicated  from  file  descriptor  digit;  see  dtip(2).  Similarly  for  the 
standard  output  using  >. 

<&—  The  standard  input  is  closed.  Similarly  for  the  standard  output  using  >. 

If  one  of  the  above  is  preceded  by  a  digit,  the  file  descriptor  created  is  that  specified  by  the  digit 
(instead  of  the  default  0  or  1).  For  example, 

...  2>&1 

creates  file  descriptor  2  to  be  a  duplicate  of  file  descriptor  1. 

If  a  command  is  followed  by  &  then  the  default  standard  input  for  the  command  is  the  empty 
file  (/dev/null).  Otherwise,  the  environment  for  the  execution  of  a  command  contains  the  file 
descriptors  of  the  invoking  shell  as  modified  by  input  output  specifications. 

Environment. 

The  environment  is  a  list  of  name-value  pairs  that  is  passed  to  an  executed  program  in  the  same 
way  as  a  normal  argument  list;  see  txtcvt{2)  and  ent;iri>rt(5).  The  shell  interacts  with  the 
environment  in  several  ways.  On  invocation,  the  shell  scans  the  environment  and  creates  a 
parameter  for  each  name  found,  giving  it  the  corresponding  value.  Executed  commands  inherit 
the  same  environment.  If  the  user  modifies  the  values  of  these  parametero  or  creates  new  ones, 
none  of  these  affects  the  environment  unless  the  export  command  is  used  to  bind  the  shell’s 
parameter  to  the  environment.  The  environment  seen  by  any  executed  command  is  thus  com¬ 
posed  of  any  unmodified  name-value  pairs  originally  inherited  by  the  shell,  plus  any  modifications 
or  additions,  all  of  which  must  be  noted  in  export  commands. 

The  environment  for  any  eimpie- command  may  be  augmented  by  prefixing  it  with  one  or  more 
assignments  to  parameters.  Thus  these  two  lines  are  equivalent 

TERM=450  cmd  args 

(export  TERM;  TERM=450;  cmd  args) 

If  the  — k  fiag  is  set,  all  keyword  arguments  are  placed  in  the  environment,  even  if  they  occur 
after  the  command  name.  The  following  prints  *a=b  c*  and  ’c’: 

echo  a=b  c 
set  — k 
echo  a=b  c 

Signals. 

The  INTERRUPT  and  QUIT  signals  for  an  invoked  command  are  ignored  if  the  command  is  fol¬ 
lowed  by  &;  otherwise  signals  have  the  values  inherited  by  the  shell  from  its  parent.  (But  see 
also  trap«) 

Execution. 

Each  time  a  command  is  executed  the  above  substitutions  are  carried  out.  Except  for  the  ’spe¬ 
cial  commands’  listed  below  a  new  process  is  created  and  an  attempt  is  made  to  execute  the  com¬ 
mand  via  an  execv€{2). 

The  shell  parameter  IPATH  defines  the  search  path  for  the  directory  containing  the  command. 
Each  alternative  directory  name  is  separated  by  a  colon  (:).  The  default  path  is  :/bin:/uBr/bln. 
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If  the  command  name  contains  a  /,  the  search  path  is  not  used.  Otherwise,  each  directory  in  the 
path  is  searched  for  an  executable  file.  If  the  file  has  execute  permission  but  is  not  an  a,oui  file, 
it  is  assumed  to  be  a  file  containing  shell  commands.  A  subshell  (that  is,  a  separate  process)  is 
spawned  to  read  it.  A  parenthesized  command  is  also  executed  in  a  subshell. 

Special  commands. 

The  following  commands  arc  executed  in  the  shell  process  and  except  where  specified  no  input 
output  redirection  is  permitted  for  such  commands. 

:  No  effect;  the  command  does  nothing. 

•  file  Read  and  execute  commands  from  file  and  return.  The  search  path  IPATH  is  used  to 
find  the  directory  containing  file. 

break  \n] 

Exit  from  the  enclosing  for  or  while  loop,  if  any.  If  n  is  specified,  break  n  levels, 

continue  [nj 

Resume  the  next  iteration  of  the  enclosing  for  or  while  loop.  If  n  is  specified,  resume  at 
the  n-th  enclosing  loop, 
cdjar^;] 

Change  the  current  directory  to  arg.  The  shell  parameter  SHOME  is  the  default  arg. 
eval  I  .  1 

The  arguments  are  read  as  input  to  the  shell  and  the  resulting  command(s)  executed, 
exec  [  ] 

The  command  specified  by  the  arguments  is  executed  in  place  of  this  shell  without  create 
ing  a  new  process.  Input  output  arguments  may  appear  and  if  no  other  arguments  are 
given  cause  the  shell  input  output  to  be  modified. 

exit  \n\ 

Causes  a  non  interactive  shell  to  exit  with  the  exit  status  specified  by  n.  If  n  is  omitted, 
the  exit  status  is  that  of  the  last  command  executed.  (An  end  of  file  will  also  exit  from 
the  shell.) 
export  [  name  . . .  ] 

The  given  names  are  marked  for  automatic  export  to  the  environment  of  subsequently- 
executed  commands.  If  no  arguments  are  given,  a  list  of  exportable  names  is  printed, 
login  \arg 

Equivalent  to  ’exec  login  arg 
newgrp  \arg  ...\ 

Equivalent  to  ’exec  newgrp  arg 
read  name  ... 

One  line  is  read  from  the  standard  input;  successive  words  of  the  input  are  assigned  to 
the  variables  name  in  order,  with  leftover  words  to  the  last  variable.  The  return  code  is 
0  unless  the  end-of-file  is  encountered, 
readonly  ( name  . . .  j 

The  given  names  are  marked  readonly  and  the  values  of  the  these  names  may  not  be 
changed  by  subsequent  assignment.  If  no  arguments  are  given,  a  list  of  all  readonly 
names  is  printed. 

set  I  — eknptuvx  |  . . .  |  ] 

— e  If  non  interactive,  exit  immediately  if  a  command  fails. 

— k  All  keyword  arguments  are  placed  in  the  environment  for  a  command,  not  just 
those  that  precede  the  command  name. 

— n  Read  commands  but  do  not  execute  them. 

— t  Exit  after  reading  and  executing  one  command. 

— u  Treat  unset  variables  as  an  error  when  substituting. 

—V  Print  shell  input  lines  as  they  are  read. 

—X  Print  commands  and  their  arguments  as  they  are  executed. 

—  Turn  off  the  — x  and  — v  options. 
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These  flags  can  also  be  used  upon  invocation  of  the  shell.  The  current  set  of  flags  may 
be  found  in  S— . 

Remaining  arguments  are  positional  parameters  and  are  assigned,  in  order,  to  tl,  $2,  etc. 
If  no  arguments  are  given,  the  values  of  all  names  are  printed. 

■hlft  The  positional  parameters  from  $2...  are  renamed  $1. . . 

times  Print  the  accumulated  user  and  system  times  for  processes  run  from  the  shell. 

trap  [ary|  |n|  ... 

Arg  is  a  command  to  be  read  and  executed  when  the  shell  receives  signal(s)  n.  (Note 
that  arg  is  scanned  once  when  the  trap  is  set  and  once  when  the  trap  is  taken.)  Trap 
commands  are  executed  in  order  of  signal  number.  If  arg  is  absent,  all  trap(s)  n  are  reset 
to  their  original  values.  If  arg  is  the  null  string,  this  signal  is  ignored  by  the  shell  and  by 
invoked  commands.  If  n  is  0,  the  command  arg  is  executed  on  exit  from  the  shell,  other¬ 
wise  upon  receipt  of  signal  r»  as  numbered  in  8igvec(2).  Trap  with  no  arguments  prints  a 
list  of  commands  associated  with  each  signal  number. 

umask  |  nnn  | 

The  user  file  creation  mask  is  set  to  the  octal  value  nnn  (see  «masifc(2)).  If  nnn  is  omit¬ 
ted,  the  current  value  of  the  mask  is  printed. 

wait  [  n] 

Wait  for  the  specified  process  and  report  its  termination  status.  If  n  is  not  given,  all 
currently  active  child  processes  arc  waited  for.  The  return  code  from  this  command  is 
that  of  the  process  waited  for. 

Invocation. 

If  the  first  character  of  argument  zero  is  — ,  commands  are  read  from  IHOME/. profile,  if  such  a 
file  exists.  Commands  are  then  read  as  described  below.  The  following  flags  are  interpreted  by 
the  shell  when  it  is  invoked. 

— c  string  If  the  — c  flag  is  present,  commands  are  read  from  string. 

If  the  — ■  flag  is  present  or  if  no  arguments  remain  then  commands  are  read  from  the 
standard  input.  Shell  output  is  written  to  file  descriptor  2. 

If  the  — i  flag  is  present  or  if  the  shell  input  and  output  are  attached  to  a  terminal 
(as  told  by  gttg)  then  this  shell  is  interactive.  In  this  case  the  terminate  signal 
SIGTERM  (see  eigt7ec(2))  is  ignored  (so  that  ’kill  0’  does  not  kill  an  interactive  shell) 
and  the  interrupt  signal  SIGINT  is  caught  and  ignored  (so  that  wait  is  interrupt- 
able).  In  all  cases  SIGQUIT  is  ignored  by  the  shell. 

The  remaining  flags  and  arguments  are  described  under  the  set  command. 

FILES 

$HOME/.  profile 
/tmp/sh* 

/dev/null 

SEE  ALSO 

Using  the  Bourne  Shell  in  the  Beginner’s  Guide  to  the  Sun  Workstation 
C5h(l),  test(l),  execve(2). 

DIAGNOSTICS 

Errors  detected  by  the  shell,  such  as  syntax  errors,  cause  the  shell  to  return  a  non  zero  exit 
status.  If  the  shell  is  being  used  non  interactively  then  execution  of  the  shell  file  is  abandoned. 
Otherwise,  the  shell  returns  the  exit  status  of  the  last  command  executed  (sec  also  exit). 

BUGS 

If  «  is  used  to  provide  standard  input  to  an  asynchronous  process  invoked  by  &,  the  shell  gets 
mixed  up  about  naming  the  input  document.  A  garbage  file  /tmp/sh*  is  created,  and  the  shell 
complains  about  not  being  able  to  find  the  file  by  another  name. 
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NAME 

shelltool  —  Run  a  shell  (or  other  program)  in  the  SunWindows  environment 
SYNOPSIS 

shelltool  [  — C  ]  [  program  |  args  ]  ] 

OPTIONS 

— C  Redirect  system  console  output  to  this  instance  of  the  shelltool. 

shelltool  also  takes  generic  tool  arguments;  see  euni0ols{l)  for  a  list  of  these  arguments. 

If  a  program  argument  is  present,  shelltool  runs  it.  If  there  are  no  arguments,  shelltool  runs  the 
program  corresponding  to  your  SHELL  environment  variable.  If  this  environment  variable  is  not 
available,  then  shelltool  runs  /bin/sh. 

DESCRIPTION 

shelltool  is  a  standard  tool  provided  with  the  environment. 

When  invoked,  shelltool  starts  up  an  interactive  character-terminal-based  program,  usually  a 
shell,  inside  of  a  terminal  emulator  subwindow.  If  this  program  is  a  shell,  it  accepts  commands 
and  runs  programs  in  the  usual  way, 

skelUoors  window  may  be  positioned  and  manipulated  in  the  same  way  as  any  tool  window  in  the 
SunWindows  environment.  sAe Woo/ supports  selections  as  described  in  swrt/oo/o(l). 

To  invoke  Tool  Manager  Functions,  position  the  cursor  on  the  name  stripe  or  on  the  outside 
borders  of  shelltooVs  window.  The  Tool  Manager  is  not  accessible  from  shelltooVs  terminal 
subwindow  because  keystrokes  are  passed  to  the  shell,  or  to  the  programs  run  from  it.  See 
Terminal  Emulators  for  more  information. 

To  run  graphics  programs,  use  gfxtool  —  see  gfxtool{l). 

Unless  you  instruct  the  system  otherwise,  it  displays  messages  for  the  console  by  writing  over  the 
windows  on  the  display.  It  bypasses  all  of  the  support  for  multiple  windows  sharing  the  bitmap. 
Solve  this  problem  by  starting  a  copy  of  shelltool  with  the  -C  argument;  [that]  redirects  system 
console  messages  into  that  instance  of  the  shelltool. 

See  for  information  on  terminal  emulators,  and  for  an  example  showing  how  shelltool 

can  be  started  automatically  when  the  windowing  environment  starts  up. 

SEE  ALSO 

gfxtool{l) 


FILES 

''/.ttyswrc 

/usr/bin/shelltool 

/usr/bin/suntools 

/usr/demo/* 

/usr/src/sun/suntool/shelltool.c 

BUGS 

This  release  has  the  following  notable  bugs: 

(1)  Remote  login  to  another  machine  should  be  done  with  a  terminal  emulator  subwindow 
matching  the  standard  terminal  size  for  the  remote  machine  (for  example,  34  by  80  char¬ 
acters  for  a  Sun  workstation).  The  remote  machine  does  not  understand  terminals  with 
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non-standard  size. 

(2)  If  more  than  256  characters  are  input  to  a  terminal  emulator  subwindow  without  an 
intervening  newline^  the  terminal  emulator  may  hang.  If  this  occurs,  display  the  Tool 
Manager  Menu;  the  "TTY  Hung?**  submenu  there  has  one  item,  **Flush  input**,  that  you 
can  invoke  to  correct  the  problem. 
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NAME 

size  —  size  of  an  object  file 

SYNOPSIS 

sise  I  object ...  ] 

DESCRIPTION 

Size  prints  the  (decimal)  number  of  bytes  required  by  the  text,  data,  and  bss  portions,  and  their 
sum  in  hex  and  decimal,  of  each  object-file  argument.  If  no  file  is  specified,  a.out  is  used. 

SEE  ALSO 

a.out(5) 
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NAME 

sleep  —  suspend  execution  for  an  interval 

SYNOPSIS 

sleep  time 

DESCRIPTION 

Sleep  suspends  execution  for  time  seconds.  It  is  used  to  execute  a  command  after  a  certain 
amount  of  time  as  in: 

(sleep  105;  command)& 

or  to  execute  a  command  every  so  often,  as  in: 

while  true 
do 

command 
sleep  37 

done 


SEE  ALSO 

setitimer(2),  sleep(3) 

BUGS 

Time  must  be  less  than  2,147,483,647  seconds. 
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NAME 

soelim  —  eliminate  .so’s  from  nroff  input 

SYNOPSIS 

Boelim  [  file  J 

DESCRIPTION 

Soelim  reads  the  specified  files  or  the  standard  input  and  performs  the  textual  inclusion  implied 
by  the  nroff  directives  of  the  form 

.so  somefile 

when  they  appear  at  the  beginning  of  input  lines.  This  is  useful  since  programs  such  as  tbl  do  not 
normally  do  this;  it  allows  the  placement  of  individual  tables  in  separate  files  to  be  run  as  a  part 
of  a  large  document. 

An  argument  consisting  of  a  single  minus  (—)  is  taken  to  be  a  file  name  corresponding  to  the 
standard  input. 

Note  that  inclusion  can  be  suppressed  by  using  ‘ instead  of  that  is, 

'so  /usr/lib/tmac.s 

EXAMPLE 

A  sample  usage  of  soelim  would  be 

soelim  exum?.n  [  tbl  j  nroff  —ms  [  col  j  Ipr 

SEE  ALSO 

colcrt(l),  more(l) 

BUGS 

The  format  of  the  source  commands  must  involve  no  strangeness  —  exactly  one  space  must  pre¬ 
cede  and  no  spaces  follow  the  file  name. 
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NAME 

sort  —  sort  or  merge  files 
SYNOPSIS 

sort  I  — mubdflnrtj?  ]  |  -^posl  (  —pos2  ]  I  •••  [  — o  name  |  |  — T  directory  ]  |  file  | 
DESCRIPTION 

Sort  sorts  lines  of  all  the  named  files  together  and  writes  the  result  on  the  standard  output.  The 
name  '  means  the  standard  input.  If  no  input  filers  are  named,  the  standard  input  is  sorted. 

The  default  sort  key  is  an  entire  line.  Default  ordering  is  lexicographic  by  bytes  in  machine  col¬ 
lating  sequence. 

The  notation  ^posl  —po$2  restricts  a  sort  key  to  a  field  beginning  at  post  and  ending  just  before 
pos2.  Pool  and  pos2  each  have  the  form  optionally  followed  by  one  or  more  of  the  flags 
bdfinr^  where  m  tells  a  number  of  fields  to  skip  from  the  beginning  of  the  line  and  n  tells  a 
number  of  characters  to  skip  further.  If  any  flags  are  present  they  override  all  the  global  order¬ 
ing  options  for  this  key.  If  the  b  option  is  in  effect  n  is  counted  from  the  first  nonblank  in  the 
field;  b  is  attached  independently  to  po82.  A  missing  .n  means  .0;  a  missing  —po82  means  the 
end  of  the  line.  Under  the  —tx  option,  fields  are  strings  separated  by  x\  otherwise  fields  are 
nonempty  nonblank  strings  separated  by  blanks. 

When  there  are  multiple  sort  keys,  later  keys  are  compared  only  after  all  earlier  keys  compare 
equal.  Lines  that  otherwise  compare  equal  are  ordered  with  all  bytes  significant. 

OPTIONS 

The  ordering  is  affected  globally  by  the  following  options,  one  or  more  of  which  may  appear, 
b  Ignore  leading  blanks  (spaces  and  tabs)  in  field  comparisons, 
d  ^Dictionary’  order:  only  letters,  digits  and  blanks  are  significant  in  comparisons, 
f  Fold  upper  case  letters  onto  lower  case. 

I  Ignore  characters  outside  the  ASCII  range  040-0176  in  nonnumeric  comparisons. 

n  An  initial  numeric  string,  consisting  of  optional  blanks,  optional  minus  sign,  and  zero  or 
more  digits  with  optional  decimal  point,  is  sorted  by  arithmetic  value.  Option  n  implies 
option  b* 

r  Reverse  the  sense  of  comparisons. 
tx  Tab  character’  separating  fields  is  j. 

These  option  arguments  are  also  understood: 

c  Check  that  the  input  file  is  sorted  according  to  the  ordering  rules;  give  no  output  unless  the 
file  is  out  of  sort. 

m  Merge  only,  the  input  files  are  already  sorted, 
o  name 

name  is  the  name  of  an  output  file  to  use  instead  of  the  standard  output.  This  file  may  be 
the  same  as  one  of  the  inputs. 

T  directory 

directory  argument  is  the  name  of  a  directory  in  which  temporary  files  should  be  made. 

u  Suppress  all  but  one  in  each  set  of  equal  lines.  Ignored  bytes  and  bytes  outside  keys  do  not 
participate  in  this  comparison. 

EXAMPLES 

Print  in  alphabetical  order  all  the  unique  spellings  in  a  list  of  words.  Capitalized  words  differ 
from  uncapitalized. 


Sun  Release  2.0 


Last  change:  8  August  1983 


303 


SORT(l) 


USER  COMMANDS 


SORT(l) 


sort  — u  +0f  +0  list 

Print  the  password  file  (poastt)rf(5))  sorted  by  user  id  number  (the  3rd  colon-separated  field), 
sort  — t:  +2n  /etc/passwd 

Print  the  first  instance  of  each  month  in  an  already  sorted  file  of  (month  day)  entries.  The 
options  — um  with  just  one  input  file  make  the  choice  of  a  unique  representative  from  a  set  of 
equal  lines  predictable. 

sort  — um  -hO  —1  dates 

FILES 

/usr/tmp/stm*,  /tmp/*  first  and  second  tries  for  temporary  files 
SEE  ALSO 

uniq(l),  comm(l),  rev(l),  join(l) 

DIAGNOSTICS 

Comments  and  exits  with  nonzero  status  for  various  trouble  conditions  and  for  disorder 
discovered  under  option  — c. 

BUGS 

Very  long  lines  are  silently  truncated. 
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NAME 

sortbib  —  sort  bibliographic  database 
SYNOPSIS 

sortbib  I  ““sKEYS  j  database 
DESCRIPTION 

Sortbib  sorts  files  of  records  containing  refer  key-letters  by  user-specified  keys.  Records  may  be 
separated  by  blank  lines,  or  by  .|  and  .|  delimiters,  but  the  two  styles  may  not  be  mixed  together. 
This  program  reads  through  each  database  and  pulls  out  key  fields,  which  are  sorted  separately. 
The  sorted  key  fields  contain  the  file  pointer,  byte  offset,  and  length  of  corresponding  records. 
These  records  are  delivered  using  disk  seeks  and  reads,  so  sortbib  may  not  be  used  in  a  pipeline 
to  read  standard  input. 

By  default,  sortbib  alphabetizes  by  the  first  %A  and  the  %D  fields,  which  contain  the  senior 
author  and  date.  The  — s  option  is  used  to  specify  new  KEYS.  For  instance,  — sATD  will  sort  by 
author,  title,  and  date,  while  -sAh-D  will  sort  by  all  authors,  and  date.  Sort  keys  past  the 
fourth  are  not  meaningful.  No  more  than  16  databases  may  be  sorted  together  at  one  time. 
Records  longer  than  4096  characters  will  be  truncated. 

Sortbib  sorts  on  the  last  word  on  the  %A  line,  which  is  assumed  to  be  the  author’s  last  name.  A 
word  in  the  final  position,  such  as  “jr.”  or  “ed.”,  will  be  ignored  if  the  name  beforehand  ends 
with  a  comma.  Authors  with  two-word  last  names  or  unusual  constructions  can  be  sorted 
correctly  by  using  the  nroff  convention  “\0”  in  place  of  a  blank.  A  %Q  field  is  considered  to  be 
the  same  as  %A,  except  sorting  begins  with  the  first,  not  the  last,  word.  Sortbib  sorts  on  the  last 
word  of  the  %D  line,  usually  the  year.  It  also  ignores  leading  articles  (like  *‘A”  or  'The”)  when 
sorting  by  titles  in  the  %T  or  %3  fields;  it  will  ignore  articles  of  any  modern  European  language. 
If  a  sort-significant  field  is  absent  from  a  record,  sortbib  places  that  record  before  other  records 
containing  that  field. 

SEE  ALSO 

refer(l),  addbib(l),  roffbib(l),  indxbib(l),  lookbib(l) 

BUGS 

Records  with  missing  author  fields  should  probably  be  sorted  by  title. 
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NAME 

spell,  spellin,  spellout  -  find  spelling  errors 
SYNOPSIS 

Bpell  (  -V  I  [  -b  j  [  -d  hlist  |  [  hstop  j  |  — h  spellhist  ]  [  file  ) 
spellin  I  list  | 
spellout  [  “d  ]  list 
DESCRIPTION 

Spell  collects  words  from  the  named  documents,  and  looks  them  up  in  a  spelling  list.  Words  that 
neither  occur  among  nor  are  derivable  (by  applying  certain  inflections,  prefixes  or  suffixes)  from 
words  in  the  spelling  list  are  printed  on  the  standard  output.  If  no  files  are  named,  words  are 
collected  from  the  standard  input. 

Spell  ignores  most  and  e?n(l)  constructions. 

The  spelling  list  is  based  on  many  sources,  and  while  more  haphazard  than  an  ordinary  diction¬ 
ary,  is  also  more  effective  in  respect  to  proper  names  and  popular  technical  words.  Coverage  of 
the  specialized  vocabularies  of  biology,  medicine  and  chemistry  is  light. 

Pertinent  auxiliary  files  may  be  specified  by  name  arguments,  indicated  below  with  their  default 
settings.  Copies  of  all  output  are  accumulated  in  the  history  file.  The  stop  list  filters  out 
misspellings  (for  example,  thier^thy— y+ier)  that  would  otherwise  pass. 

Two  routines  help  maintain  the  hash  lists  used  by  spell.  Both  expect  a  list  of  words,  one  per  line, 
from  the  standard  input.  Spellin  adds  the  words  on  the  standard  input  to  the  preexisting  list 
and  places  a  new  list  on  the  standard  output.  If  no  list  is  specified,  the  new  list  is  created  from 
scratch.  Spellout  looks  up  each  word  in  the  standard  input  and  prints  on  the  standard  output 
those  that  are  missing  from  (or  present  on,  with  option  --d)  the  hash  list. 

OPTIONS 

—V  Print  all  words  not  literally  in  the  spelling  list,  as  well  as  plausible  derivations  from  spel¬ 
ling  list  words. 

— b  Check  British  spelling.  Besides  preferring  centre,  colour,  speciality,  travelled,  and  so  on, 

the  — b  option  insists  upon  -ise  in  words  like  standardise,  Fowler  and  the  OED  to  the 
contrary  notwithstanding. 

—X  print  every  plausible  stem  with  *=’  for  each  word. 

FILES 

/usr/dict/hlist|abj 
/usr/dict/hstop 
/usr/dict/spellhist 
/usr/dict/words 
/usr /lib/spell 

SEE  ALSO 

deroff(l),  sort(l),  tee(l),  sed(l) 

BUGS 

The  spelling  list’s  coverage  is  uneven;  new  installations  will  probably  wish  to  monitor  the  output 
for  several  months  to  gather  local  additions. 

British  spelling  was  done  by  an  American. 


hashed  spelling  lists,  American  &  British 
hashed  stop  list 
history  file 

list  of  words 
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NAME 

spline  —  interpolate  smooth  curve 
SYNOPSIS 

Bpline  1  -a  ]  [  -k  j  [  -n  )  I  -p  ]  [  -X  I 
DESCRIPTION 

Spline  takes  pairs  of  numbers  from  the  standard  input  as  abcissas  and  ordinates  of  a  function.  It 
produces  a  similar  set,  which  is  approximately  equally  spaced  and  includes  the  input  set,  on  the 
standard  output.  The  cubic  spline  output  (R.  W.  Hamming,  Numerical  Methods  for  Scientists 
and  Engineers,  2nd  ed.,  349ff)  has  two  continuous  derivatives,  and  sufficiently  many  points  to 
look  smooth  when  plotted,  for  example  by  ^r<ipA(lG). 

OPTIONS 

—a  Supply  abscissas  automatically  (they  are  missing  from  the  input);  spacing  is  given  by  the 
next  argument,  or  is  assumed  to  be  1  if  next  argument  is  not  a  number. 

—k  The  constant  k  used  in  the  boundary  value  computation 

<  =  <  -  K-r 

is  set  by  the  next  argument*  By  default  A  =  0. 

— n  Space  output  points  so  that  approximately  n  intervals  occur  between  the  lower  and  upper  x 
limits.  (Default  n  —  100.) 

“P  Make  output  periodic,  that  is,  match  derivatives  at  ends.  First  and  last  input  values  should 
normally  agree. 

—X  Next  1  (or  2)  arguments  are  lower  (and  upper)  x  limits.  Normally  these  limits  are  calcu¬ 
lated  from  the  data.  Automatic  abcissas  start  at  lower  limit  (default  0). 

SEE  ALSO 

graph(lG) 

DIAGNOSTICS 

When  data  is  not  strictly  monotonic  in  x,  spline  reproduces  the  input  without  interpolating  extra 
points. 

BUGS 

A  limit  of  1000  input  points  is  enforced  silently. 
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NAME 

split  —  split  a  file  into  pieces 
SYNOPSIS 

split  [  —number  ]  (  tnfile  [  outfile  ]  ] 

DESCRIPTION 

Split  reads  file  and  writes  it  in  n-line  pieces  (default  1000)  onto  a  set  of  output  files  (as  many  files 
as  necessary).  The  name  of  the  first  output  file  is  outfile\  with  aa  appended,  the  second  file  is 
outfileab,  and  so  on  lexicographically. 

If  no  outfile  is  given,  x  is  used  as  default  (output  files  will  be  called  zaa,  ;rab,  etc.). 

If  no  infite  is  given,  or  if  —  is  given  in  its  stead,  then  the  standard  input  file  is  used. 

OPTIONS 

—number  Number  of  lines  in  each  piece. 
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NAME 

strings  —  find  printable  strings  in  an  object,  or  other  binary,  file 
SYNOPSIS 

strings  [  —  I  [  -*-0  )  [  ^number  |  file  ••• 

DESCRIPTION 

Strings  looks  for  ascii  strings  in  a  binary  file.  A  string  is  any  sequence  of  4  or  more  printing  char¬ 
acters  ending  with  a  newline  or  a  null. 

Strings  is  useful  for  identifying  random  object  files  and  many  other  things. 

OPTIONS 

—  Look  everywhere  in  the  file  for  strings.  If  this  flag  is  omitted,  strings  only  looks  in  the 
initialized  data  space  of  object  files. 

— o  Precede  each  string  by  its  offset  in  the  file  (in  octal). 

—number 

Use  number  as  the  minimum  string  length  rather  than  4. 

SEE  ALSO 
od(l) 

BUGS 

The  algorithm  for  identifying  strings  is  extremely  primitive. 
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NAME 

strip  —  remove  symbols  and  relocation  bits 

SYNOPSIS 

strip  name 

DESCRIPTION 

Strip  removes  the  symbol  table  and  relocation  bits  ordinarily  attached  to  the  output  of  the 
assembler  and  loader.  This  is  useful  to  save  space  after  a  program  has  been  debugged. 

The  effect  of  strip  is  the  same  as  use  of  the  — s  option  of  Id. 

FILES 

/tmp/stm?  temporary  file 

SEE  ALSO 

id(i) 
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NAME 

stty  —  set  terminal  options 

SYNOPSIS 

stty  I  option  ...  | 

DESCRIPTION 

Stty  sets  certain  I/O  options  on  the  current  output  terminal,  and  directs  its  output  to  the  diag¬ 
nostic  output.  With  no  argument,  it  reports  the  speed  of  the  terminal  and  the  settings  of  options 
which  are  different  from  their  defaults.  With  the  argument  “all”,  all  normally-used  option  set¬ 
tings  are  reported.  With  the  argument  “everything”,  everything  etty  knows  about  is  printed. 

OPTIONS 

Options  to  stty  are  selected  from  the  following  set: 

even  allow  even  parity  input 

—even  disallow  even  parity  input 

odd  allow  odd  parity  input 

—odd  disallow  odd  parity  input 

raw  raw  mode  input  (no  input  processing  (erase,  kill,  interrupt, ...);  parity  bit  passed  back) 

—raw  negate  raw  mode 

cooked  same  as  raw^ 

cbreak  make  each  character  available  to  reud(2)  as  received;  no  erase  and  kill  processing,  but 
all  other  processing  (interrupt,  suspend,  ...)  is  performed 
—cbreak  make  characters  available  to  read  only  when  newline  is  received 
— nl  allow  carriage  return  for  new-line,  and  output  CR-LF  for  carriage  return  or  new-line 

nl  accept  only  new-line  to  end  lines 

echo  echo  back  every  character  typed 

—echo  do  not  echo  characters 

lease  map  upper  case  to  lower  case 

—lease  do  not  map  case 

tandem  enable  flow  control,  so  that  the  system  sends  out  the  stop  character  when  its  internal 
queue  is  in  danger  of  overflowing  on  input,  and  sends  the  start  character  when  it  is 
ready  to  accept  further  input 
—tandem  disable  flow  control 

—tabs  replace  tabs  by  spaces  when  printing 

tabs  preserve  tabs 

ek  set  erase  and  kill  characters  to  ‘H  (control-H)  and  "U 

For  the  following  commands  which  take  a  character  argument  c,  you  may  also  specify  c  as  the 
“u”  or  “undef”,  to  set  the  value  to  be  undefined,  A  value  of  “"x”,  a  2  character  sequence,  is  also 
interpreted  as  a  control  character,  with  representing  delete. 

erase  c  set  erase  character  to  c  (default 

kill  c  set  kill  character  to  c  (default 

Intr  c  set  interrupt  character  to  c  (default 

quit  c  set  quit  character  to  c  (default  ‘"V). 

start  c  set  start  character  to  c  (default 

stop  c  set  stop  character  to  c  (default  ‘"S’). 

eof  c  set  end  of  file  character  to  c  (default  ‘"D’). 

brk  c  set  break  character  to  c  (default  undefined.)  This  character  is  an  extra  wakeup  caus¬ 
ing  character. 

crO  crl  cr2  cr3 

select  style  of  delay  for  carriage  return  (see  ioctl{2)) 

nlO  nil  nl2  nl3 

select  style  of  delay  for  linefeed 

tabO  tabl  tab2  tab3 
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select  style  of  delay  for  tab 
flD  ffl  select  style  of  delay  for  form  feed 

bsO  bsl  select  style  of  delay  for  backspace 

tty33  set  all  modes  suitable  for  the  Teletype  Corporation  Model  33  terminal. 

tty37  set  all  modes  suitable  for  the  Teletype  Corporation  Model  37  terminal. 

vt05  set  all  modes  suitable  for  Digital  Equipment  Corp.  VT05  terminal 

dec  set  all  modes  suitable  for  Digital  Equipment  Corp.  operating  systems  users;  (erase,  kill, 

and  interrupt  characters  to  *?,  "U,  and  ‘C,  decctlq  and  “newert”.) 

tn300  set  all  modes  suitable  for  a  General  Electric  TermiNet  300 

ti700  set  all  modes  suitable  for  Texas  Instruments  700  series  terminal 

tek  set  all  modes  suitable  for  Tektronix  4014  terminal 

0  hang  up  phone  line  immediately 

50  75  110  134  150  200  300  600  1200  1800  2400  4800  0600  10200  exta  extb 

Set  terminal  baud  rate  to  the  number  given,  if  possible.  (These  are  the  speeds  sup¬ 
ported  by  the  DH-11  interface). 

The  driver  which  supports  the  job  control  processing  of  csft(l)  is  fully  described  in  Kif(4).  The 
options  in  the  list  below  can  only  be  selected  by  using  the  new  option  to  »«y(l). 

new  Use  new  driver  (switching  flushes  typeahead). 

ert  Set  options  for  a  CRT  (ertbs,  ctlecho  and,  if  >=  1200  baud,  erterase  and  crtkill.) 

ertbs  Echo  backspaces  on  erase  characters. 

prterase  For  printing  terminal  echo  erased  characters  backwards  within  “\”  and  “/”. 
erterase  Wipe  out  erased  characters  with  “backspace-space-backspace.” 

—erterase 

Leave  erased  characters  visible;  just  backspace, 
crtkill  Wipe  out  input  on  like  kill  ala  erterase. 

—crtkill  Just  echo  line  kill  character  and  a  newline  on  line  kill. 

ctlecho  Echo  control  characters  as  “‘x”  (and  delete  as  “*?”.)  Print  iwo  backspaces  following 
the  EOT  character  (default  ‘*D’). 

—ctlecho  Control  characters  echo  as  themselves;  in  cooked  mode  EOT  (default  ‘‘D’)  is  not 
echoed. 

decctlq  After  output  is  suspended  (normally  by  ‘S),  only  a  start  character  (normally  "Q)  will 
restart  it.  This  is  compatible  with  DEXJ’s  vendor  supplied  systems. 

—decctlq  After  output  is  suspended,  any  character  typed  will  restart  it;  the  start  character  will 
restart  output  without  providing  any  input.  (This  is  the  default.) 
tostop  Background  jobs  stop  if  they  attempt  terminal  output. 

— tostop  Output  from  background  jobs  to  the  terminal  is  allowed, 
tilde  Convert  to  on  output  (for  Hazeltine  terminals). 

—tilde  Leave  poor  alone. 

flusho  Output  is  being  discarded  usually  because  user  hit  ‘*0’  (internal  state  bit). 

— flusho  Output  is  not  being  discarded. 

pendin  Input  is  pending  after  a  switch  from  ebreak  to  cooked  and  will  be  re-input  when  a 
read  becomes  pending  or  more  input  arrives  (internal  state  bit). 

—pendin  Input  is  not  pending. 

Intrup  Send  a  signal  (SIGTINT)  to  the  terminal  control  process  group  whenever  an  input 
record  (line  in  cooked  mode,  character  in  ebreak  or  raw  mode)  is  available  for  read¬ 
ing. 

—Intrup  Don’t  send  input  available  interrupts. 

mdmbuf  Start /stop  output  on  carrier  transitions  (not  implemented). 

— mdmbuf 

Return  error  if  write  attempted  after  carrier  drops, 
litout  Send  output  characters  without  any  processing. 
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— litout 
nohang 
—nohang 
etxack 


Do  normal  output  processing,  inserting  delays,  etc. 

Don^t  send  hangup  signal  if  carrier  drops. 

Send  hangup  signal  to  control  process  group  when  carrier  drops. 
Diablo  style  etx/ack  handshaking  (not  implemented). 


The  following  special  characters  are  applicable  only  to  the  new  teletype  driver  and  are  not  nor¬ 
mally  changed. 


8U8p  C 

dsusp  c 
rprnt  c 
flush  c 
werase  c 
Inext  c 


set  suspend  process  character  to  c  (default 

set  delayed  suspend  process  character  to  c  (default  *"Y^). 

set  reprint  line  character  to  c  (default 

set  flush  output  character  to  c  (default 

set  word  erase  character  to  c  (default 

set  literal  next  character  to  c  (default 


SEE  ALSO 

ioctl(2},  tset(l},  tty(4) 


Sun  Release  2.0 


Last  change:  19  March  1984 


313 


SU(1) 


USER  COMMANDS 


SU(1) 


NAME 

su  —  substitute  user  id  temporarily 
SYNOPSIS 

BU  [  username  1  I  —  ]  (  — c  command  ]  (  — f  1 
DESCRIPTION 

Su  changes  your  login  to  that  of  the  specified  username,  Su  asks  for  the  password,  just  as  if  you 
were  logging  in  as  username,  and,  if  the  password  is  given,  changes  to  that  username  and  invokes 
the  shell  specified  in  the  password  file  for  that  username,  without  changing  the  current  directory. 
The  user  environment  is  thus  unchanged  except  for  HOME  and  SHELL,  which  are  taken  from  the 
password  file  for  the  user  being  substituted  (see  env>ron(5)).  The  new  user  ID  stays  in  force  until 
the  shell  exits. 

If  no  username  is  specified,  ‘root’  is  assumed.  To  remind  the  super-user  of  his  responsibilities, 
the  Shell  substitutes  *#*  for  its  usual  prompt. 

OPTIONS 

•  The  -  flag  performs  a  complete  login.  That  is,  it  moves  to  the  home  directory,  reads  the 

,(ogin  file,  and  reads  the  shell, 

— c  command 

execute  command  after  logging  in  as  the  new  user. 

— f  Perform  a  fast  login.  That  is,  do  not  change  directories,  do  not  read  the  ,c8krc  file,  and 

do  not  read  the  .login  file  for  the  new  user  ID  to  configure  the  new  shell. 

If  the  —  and  -f  flags  are  omitted,  only  the  shell. 

SEE  ALSO 

sh(l),  csh(l) 
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NAME 

sum  “  sum  and  count  blocks  in  a  file 

SYNOPSIS 

sum  file 

DESCRIPTION 

Sum  calculates  and  displays  a  16-bit  checksum  for  the  named  file,  and  also  displays  the  size  of 
the  file  in  kilobytes.  It  is  typically  used  to  look  for  bad  spots,  or  to  validate  a  file  communicated 
over  some  transmission  line. 

SEE  ALSO 
wc(l) 

DIAGNOSTICS 

Read  error  is  indistinguishable  from  end  of  file  on  most  devicesj  check  the  block  count. 
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NAME 

sun  —  is  current  machine  a  Sun  Workstation 
SYNOPSIS 


If  Bun;  then  •••;  fl 

(sh) 

if  {  Bun  }  then 

(csh) 

endif 

DESCRIPTION 

The  sun  command  is,  on  Sun  Workstations,  the  same  as  <rtte(l);  on  VAX’es  and  other  machines 
it  is  the  same  as  false{l). 

SEE  ALSO 

false(l),  true(l),  vax(l) 
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NAME 

suntools  —  Run  the  Sun  Windows  environment 
SYNOPSIS 

Buntools  [  — n  [  — s  startup  file  ]  [  —d  display  device  \  (  — m  mouse  device  | 

[  — k  keyboard  device  j  [  — b  red  green  blue  ]  [  — f  red  green  blue  ]  |  |  [  I  [—  [  B  |  P  j  P  |  ] 

GETTING  STARTED 

suntools  starts  up  the  SunWindows  environment  and  awaits  your  directions.  You  will  often  give 
directions  by  selecting  a  menu  item.  If  your  /dev  directory  has  not  been  initialized  for  the  win¬ 
dow  environment,  suntools  will  fail;  see  Initialization  below  for  details.  If  there  is  a  file  called 
.suntools  in  your  home  directory,  suntools  stB^ris  the  application  programs  specified  in  that 

file.  You  can  find  the  format  of  the  .suntools  file  described  in  detail  under  Start-up  Processing 
below. 

The  SunWindows  system  is  ready  when: 

1)  the  screen  is  painted  with  a  standard  pattern  (usually  light  gray,  see  OPTIONS) 

2)  an  arrow-shaped  cursor  appears  on  the  screen,  tracking  motions  of  the  mouse.  An  opti¬ 
cal  mouse  must  be  on  its  special  pad  before  it  can  be  tracked.  Sometimes  the  cursor  will 
not  move  at  start-up;  moving  the  mouse  in  large  circles  for  a  few  seconds  brings  the  cur¬ 
sor  to  life. 

See  Multiple/ Color  Displays  for  information  about  running  suntools  on  more  than  one  display  at 
the  same  time  or  on  color  displays. 

OPTIONS 

— -n  Bypasses  startup  processing  by  ignoring  the  .suntools  file.  See  Startup  Processing  for 

more  on  startup  processing. 

—s  startup  file 

Read  startup  commands  from  startup  file  (instead  of  ’'/.suntools). 

— d  display  device 

Use  display  device  as  the  output  device  on  which  to  run.  If  this  option  is  not  specified, 
SunWindows  output  goes  to  the  default  frame  buffer  device,  /dev/fb. 

—m  mouse  device 

Use  mouse  device  as  the  system  pointing  device  (locator).  If  this  option  is  not  specified, 
SunWindows  uses  the  default  mouse  device,  /dev/ mouse. 

— k  keyboard  device 

Accept  keyboard  input  from  keyboard  device.  If  this  option  is  not  specified,  SunWindows 
uses  the  default  keyboard  device,  /dev/khd. 

—b  red  green  blue 

Specifies  the  values  of  the  red,  green  and  blue  components  of  the  background  color.  If 
this  option  is  not  specified,  each  component  of  the  background  color  is  255  (white).  See 
the  —f  option  for  more  details, 

— f  red  green  blue 

Specifies  the  values  of  the  red,  green  and  blue  components  of  the  foreground  color.  For 
most  color  screens,  values  must  be  between  0  and  255  where  0  is  the  absence  of  color  and 
255  is  the  maximum  intensity  of  that  color.  If  this  option  is  not  specified,  each  com¬ 
ponent  of  the  foreground  color  is  0  (black). 

—1  Invert  the  background  and  foreground  colors  used  on  the  screen.  On  a  monochrome 
monitor,  this  option  provides  a  video  reversed  image.  On  a  color  monitor,  colors  that 
are  not  used  as  the  background  and  foreground  are  not  affected. 
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— p  Displays  the  name  of  the  window  device  used  for  the  suntooh  window. 

— B  Uses  the  background  color  for  the  suntools  window  color. 

— F  Uses  the  foreground  color  for  the  suntools  window  color. 

— P  Uses  a  stipple  pattern  for  the  suntools  window  color.  If  no  -F,  -B  or  -P  option  is  given, 
-P  is  assumed. 

DESCRIPTION 

Windows 

The  SunWindows  environment  always  has  one  window  open  which  covers  the  whole  screen;  this 
is  called  the  Root  Window.  A  solid  color  is  the  only  content  of  the  Root  Window;  it  serves  as  a 
backdrop  tor  the  SunWindows  environment.  Tools  that  run  in  the  environment  are  given  their 
own  windows  which  lie  on  top  of  portions  of  the  Root  Window  (and  possibly  other  tools).  A  win¬ 
dow  obscures  any  portions  of  another  window  which  lies  below  it.  Only  the  topmost  window  is 
guaranteed  to  be  fully  visible,  and  the  Root  Window  color  shows  through  only  in  areas  which 
have  no  tool  windows  on  them. 

Input  to  Windows 

When  you  type  on  the  keyboard,  move  the  mouse,  or  press  mouse  buttons,  be  sure  your  mouse 
cursor  is  inside  the  window  you  want  to  affect.  Otherwise,  your  input  gets  lost  or  sent  to  a 
different  window. 

Your  input  actions  are  queued  for  each  window,  with  mouse  motions  and  button  pushes 
integrated  with  keystrokes.  This  means  that  you  can  type  some  characters  to  one  window,  move 
the  mouse  to  another  window,  then  type  or  use  the  mouse  in  the  second  window  before  the  first 
window  has  processed  its  input.  Each  tool’s  input  handling  is  described  with  the  rest  of  its 
behavior  in  its  section  within  the  Commands  Reference  Manual. 


The  Mouse 

Use  the  mouse  buttons  as  follows: 

Left  button  (the  #e/ec<  button)  Click  once  to  select  or  choose  objects. 

Middle  button  (the  adjust  button)  Click  once  to  shorten  or  lengthen  your  selection. 

Right  button  (the  menu  button)  Depress  and  hold  down  to  invoke  menus. 

The  exact  interpretation  of  your  actions  depends  on  the  type  of  window  receiving  them.  Any 
window  type  or  tool  that  interprets  mouse  input  differently  has  the  differences  documented  in  its 
separate  section. 

Menus 

You  can  invoke  many  functions  in  suntools  by  using  the  mouse  and  a  pop-up  menu.  When  you 
press  down  on  the  menu  button  and  hold  it  down,  the  menu(s)  appropriate  to  the  window 
appear.  Remember  that  the  mouse  cursor  must  be  in  the  window,  or  you  may  get  unexpected 
results. 

As  you  press  the  menu  button,  the  menu  appears  on  the  screen  near  the  current  location  of  the 
mouse.  The  cursor  changes  to  a  right-pointing  arrow  called  the  pointer.  The  menu  remains  on 
the  screen  as  long  as  you  hold  the  menu  button  down.  Move  the  pointer  with  the  mouse.  To 
invoke  a  menu  item,  point  at  it  (it  will  be  highlighted),  then  release  the  menu  button. 
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You  may  see  more  than  one  menu  presented  simultaneously;  generally  this  occurs  when  several 
different  classes  of  actions  are  possible  in  the  current  context.  The  menus  are  presented  in  a 
stack,  with  the  label  of  each  menu  visible,  and  with  the  current  menu  on  top  so  its  items  are  also 
visible.  To  bring  another  menu  to  the  top,  thus  making  its  items  available,  invoke  its  label  as 
you  would  a  menu  item.  That  is,  position  the  cursor  in  the  label  of  the  desired  menu  and  release 
the  menu  button.  Then  push  the  menu  button  again.  The  stack  of  menus  is  repainted  with  the 
selected  menu  on  top,  and  menu  operations  may  continue.  Another  way  to  bring  a  rear  menu 
forward  is  to  press  and  release  the  select  mouse  button  while  the  pointer  is  over  the  label  of  the 
desired  menu,  holding  the  menu  button  down  the  whole  time.  This  rearranges  the  menus 
without  removing  them  from  the  screen. 


The  Suntools  Menu 

The  Root  Window’s  default  menu  (the  Suntools  Menu)  contains  four  job-control  functions.  To 
invoke  it,  move  the  pointer  anywhere  in  the  Root  Window,  then  depress  and  hold  down  the  menu 
button. 


The  items  in  the  Suntools  Menu  are: 


New  Shell  Creates  a  new  Shell  Tool. 

A  tool  running  a  new  copy  of  the  shell  appears  on  the  screen.  The  window  is 
placed  on  the  screen  on  top  of  everything  it  overlaps.  Its  initial  size  can  display 
80  columns  and  34  rows  of  characters. 


New  Graphics  Creates  a  new  Graphics  Tool. 

Creates  a  new  tool  window  appropriate  for  running  graphics  programs.  It  is 
placed  on  the  screen  on  top  of  everything  it  overlaps. 

Exit  Exits  the  suntools  program. 

Closes  all  tool  windows  and  kills  their  associated  processes.  You  return  to  the 
shell  which  invoked  suntools.  This  command  requires  confirmation:  When  it 
prompts  you,  press  the  left  mouse  button  to  complete  the  Exit  command;  press 
the  right  button  to  cancel. 


ReDisplay  All  Redraws  all  the  contents  of  the  screen. 

Use  this  to  repair  damage  done  by  processes  that  wrote  to  the  screen  without 
consulting  the  SunWindows  system.  See  8helltool{l)  for  details  on  how  to  avoid 
this. 


The  Root  Window  ignores  most  keyboard  input;  if  you  type  while  the  cursor  is  over  an  exposed 
portion  of  the  Root  Window,  the  keystrokes  are  simply  discarded  (without  any  audible  or  visible 
feedback). 


The  Tool  Manager 

Tools  interpret  most  of  your  input  in  their  own  fashion;  for  instance,  many  tools  incorporate  a 
terminal  emulator  running  a  shell.  Tools  also  provide  you  with  a  small  set  of  universal  functions 
through  the  Tool  Manager  menu. 

You  can  invoke  the  Tool  Manager  menu  when  the  cursor  is  over  a  portion  of  the  tool  which  does 
not  impose  some  other  interpretation  on  your  input.  For  any  tool,  the  tool  namestripe  (black 
stripe  holding  the  tool’s  name),  the  border  stripes  of  the  window,  and  the  whole  of  the  tool’s  icon 
are  such  areas. 

The  items  in  this  menu  are: 

Close  (or  Open)  Only  one  of  ‘‘Close”  or  “Open”  appears  in  the  menu,  as  appropriate  to  the 
current  state  of  the  window.  Close  shrinks  the  tool  to  a  small  image  on  the 
screen.  Open  reopens  a  closed  window  and  places  it  in  the  spot  it  occupied  when 
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Move 


Stretch 


Expose 


Hide 


ReDisplay 

Quit 


it  was  last  open. 

when  the  window  is  closed,  the  tool’s  process(es)  continue  to  run.  Closed  win¬ 
dows  are  placed  by  default  in  the  lower  left  of  the  screen,  filling  in  rows  to  the 
right,  and  then  bottom- to- top,  in  the  order  they  are  created.  You  can  move  a 
closed  window  just  like  an  open  window.  If  you  reopen  it  and  close  it  again,  it 
returns  to  its  last  position  on  the  screen,  without  affecting  its  size  or  contents. 

Move  the  tool  window  to  another  spot  on  the  screen. 

When  invoked,  Move  instructs  you  to  grasp  the  window  by  depressing  and  hold¬ 
ing  down  either  the  left  or  middle  mouse  buttons,  or  to  cancel  the  operation  by 
pressing  the  right  button.  Depressing  any  mouse  button  removes  these  instruc¬ 
tions  from  the  screen. 

When  you  depress  either  the  left  or  middle  button,  a  box  called  a  bounding  box 
outlines  the  window.  The  bounding  box  tracks  the  mouse  as  long  as  you  hold 
that  button  down.  When  you  press  the  button,  the  cursor  location  determines 
how  the  window  is  moved.  If  the  mouse  cursor  is  near  a  corner  when  you  press 
the  button,  that  corner  of  the  box  attaches  to  the  mouse  cursor.  If  it  is  in  the 
middle  third  of  a  side,  then  the  midpoint  of  the  box’s  side  attaches  to  the  mouse 
cursor. 

Position  the  bounding  box  where  you  want  the  window  to  go  and  release  the 
mouse  button.  If  the  window  is  on  top  of  or  underneath  other  windows  before 
you  move  it,  it  will  be  on  top  of  or  underneath  the  same  windows  after  you 
move  it. 

Shrinks  or  stretches  the  size  of  a  window  on  the  screen. 

Stretch  works  almost  like  Move.  Depress  and  hold  down  either  the  left  or  middle 
mouse  buttons  to  grasp  the  window.  Cancel  the  operation  by  pressing  the  right 
button. 

When  you  depress  either  the  left  or  middle  button,  a  bounding  box  outlines  the 
window.  The  bounding  box  tracks  the  mouse  as  long  as  you  hold  that  button 
down.  When  you  press  the  button,  your  action  determines  how  the  window  is 
stretched.  If  the  mouse  cursor  is  near  a  corner  when  you  press  the  button,  both 
of  the  sides  that  form  that  corner  are  adjusted;  the  opposite  corner  remains 
fixed.  If  it  is  in  the  middle  third  of  a  side,  then  only  that  side  is  adjusted. 

Adjust  the  bounding  box  to  the  shape  you  want  the  window  to  take,  and  release 
the  mouse  button.  If  the  window  is  on  top  of  or  underneath  other  windows 
before  you  move  it,  it  will  be  on  top  of  or  underneath  the  same  windows  after 
you  stretch  it. 

Brings  the  window  to  ‘the  top  of  the  heap’. 

The  whole  window  becomes  visible,  and  occludes  any  window  it  happens  to  over¬ 
lap  on  the  screen.  Its  position  on  the  screen  does  not  change. 

Puts  the  window  on  the  ‘bottom  of  the  heap’. 

The  window  is  occluded  by  any  window  which  overlaps  it.  Its  position  on  the 
screen  does  not  change. 

Redraws  the  contents  of  the  window. 

Notifies  the  tool  to  terminate  gracefully. 

This  command  requires  the  same  type  of  confirmation  as  the  Exit  command  in 
the  Suntools  Menu. 


In  many  multi-subwindow  tools,  you  can  adjust  the  boundary  between  two  subwindows  up  or 
down  without  changing  the  overall  size  of  the  tool.  Depress  the  middle  mouse  button  over  the 
boundary.  A  bounding  box  is  drawn  for  the  subwindow  above  or  to  the  left  of  the  selected 
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boundary.  Now  adjust  the  size  of  that  subwindow,  exactly  as  with  the  Stretch  operation.  When 
the  button  is  released,  that  subwindow  is  adjusted  to  the  size  indicated,  and  the  remaining  area 
of  the  too!  is  allotted  to  the  other  subwindows. 

Tool  Management  Accelerators 

Accelerators  are  provided  for  some  of  the  Tool  Manager  functions.  You  can  invoke  these  func¬ 
tions  quickly  with  a  simple  button  push  in  the  tool  window,  rather  than  displaying  a  menu. 

The  accelerators  for  the  various  functions  are: 

Open  To  open  an  iconic  tool,  click  the  select  mouse  button  when  the  cursor  is  over 

the  icon. 

Move  To  invoke  Move,  depress  the  middle  mouse  button  while  the  cursor  is  in  the  tool 

window’s  name  stripe  or  outer  boundary.  A  bounding  box  displays  and  tracks 
the  mouse  as  long  as  you  hold  the  middle  button  down.  Release  the  button 
when  the  box  indicates  the  spot  where  you  want  to  place  the  window. 

Expose  To  expose  a  window,  click  the  left  mouse  button  at  an  open  tool  window  while 

the  cursor  is  on  the  tool’s  name  stripe  or  outer  boundary. 

Help  To  get  help,  type  a  question  mark  to  a  tool  window.  A  help  message  explaining 

the  materia!  covered  here  appears. 

Generic  Tool  Arguments 

Most  tools  now  take  the  following  arguments  in  their  command  lines: 


FLAG  (LONG  FLAG) 

ARCS 

NOTES 

-Ww 

(-width) 

columns 

-Wh 

(-height) 

lines 

-Ws 

(-size) 

xy 

X  and  y  are  in  pixels 

-Wp 

(-position) 

xy 

X  and  y  are  in  pixels 

-WP 

(-icon_position) 

xy 

X  and  y  are  in  pixels 

-Wi 

(-label) 

string 

-Wi 

(-iconic) 

makes  the  tool  start  iconic 

-Wt 

(-font) 

filename 

-Wf 

(-foreground_color) 

red  green  blue 

0-255  (no  color-full  color) 

-Wb 

(-background_color) 

red  green  blue 

0-255  (no  color-full  color) 

-Wg 

(-set_defau!t_coIor) 

(apply  color  to  subwindows  too) 

-WI 

(-iconjmage) 

filename 

(for  tools  with  non-default  icons) 

-WL 

(-iconjabel) 

«  .  •  ft 

string 

(for  tools  with  non-default  icons) 

-WT 

(-iconjont) 

filename 

(for  tools  with  non-default  icons) 

-WH 

(-help) 

print  this  table 

Each 

flag  option  may  be  specified  in  either  its  short  form  or  its  long  form;  the  two  are  completely 

synonymous. 

Terminal  Emulators 

Several  tools  provide  a  terminal  emulator  running  a  shell  in  some  part  of  their  window.  When 
you  type  to  this  subiuindow,  the  keystrokes  pass  through  to  the  shell  program  running  in  it, 
rather  than  being  handled  by  the  tool.  These  tools  provide  Tool  Manager  functions  only  when 
the  cursor  is  in  their  name  stripe  or  borders.  Similarly,  output  from  the  shell  program  displays 
in  the  subwindow. 
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Whenever  a  tty  subwindow  is  created,  the  startup  file  ‘/.ttyswrc  is  parsed  for  tty  subwindow- 
specific  parameters.  A  sample  .ttyswrc  file  may  be  found  at  the  end  of  this  section.  The  com¬ 
mand  format  of  this  file  is: 


# 

set  variable 
map!  key  text 
roapo  key  text 


Comment. 

Turn  on  the  specified  variable. 

When  key  is  typed  pretend  text  was  typed. 
When  key  is  typed  pretend  text  was  output. 


The  only  currently  defined  "variable"  is  "pagemode".  "Key"  is  one  of  L1-L15,  F1-F15,  T1-T15, 
R1-R15,  LEFT,  or  RIGHT  (see  note  below).  "Text"  may  contain  escapes  such  as  \E,  \n,  'X,  etc. 
(escape,  newline,  control-X,  respectively).  See  tertncap{b)  for  the  format  of  the  string  escapes  that 
are  recognized.  Note  that  "mapi"  and  "mapo"  may  be  replaced  by  another  keymapping  mechan¬ 
ism  in  the  future. 


NOTE:  When  using  the  default  kernel  keyboard  tables,  the  keys  LI,  LEFT,  RIGHT,  BREAK,  R8, 
RIO,  R12,  and  R14  cannot  be  mapped  in  this  way  because  they  send  special  values  to  the  termi¬ 
nal  emulator  subwindow.  See  kbd{b)  for  more  information. 

It  is  possible  to  have  terminal-based  programs  drive  the  tool  in  which  its  tty  subwindow  resides 
by  sending  it  special  escape  sequences.  These  escape  sequences  may  also  be  sent  using  the  "mapo" 
function  described  above.  The  following  functions  pertain  to  the  tool  in  which  the  tty  subwindow 
resides,  not  the  tty  subwindow  itself. 


\E[lt 

\E[2t 

\E[3t 

\E  [3;TOP;LEFTt 
\E[4t 

\E [4;WIDTH;HTt 
\E[5t 
\E  [6t 
\E  [7t 

\E [8;R0WS;C0LSt 
\E [lit 
\E [13t 
\E [14t 
\E [18t 
\E [20t 
\E  [21t 

\E]l<text>\E\ 

\E]I<file>\E\ 

\E]L<label>\E\ 
\E[>OPT;  .  .  .h 
\E[>OPT; . .  .k 
\E  [>OPT; ... 1 


—  open 

—  close  (become  iconic) 

—  move,  with  interactive  feedback 

—  move,  to  TOP  LEFT  (pixel  coordinates) 

—  stretch,  with  interactive  feedback 

—  stretch,  to  WIDTH  HT  size  (in  pixels) 

—  top  (expose) 

—  bottom  (hide) 

—  refresh 

—  stretch,  to  ROWS  COLS  size  (in  characters) 

—  report  if  open  or  iconic  by  sending  \B  [It  or  \E  [2t 

—  report  position  by  sending  \E  [3;TOP;LEFTt 

—  report  size  in  pixels  by  sending  \E  [4;WIDTH;HTt 

—  report  size  in  characters  by  sending  \E  [8;R0WS;C0LSt 

—  report  icon  label  by  sending  \E]Llabel\E\ 

—  report  tool  header  by  sending  \E3  llabel\E\ 

—  set  tool  header  to  <tGxt> 

—  set  icon  to  the  icon  contained  in  <file>; 

<file>  must  be  in  output  format 

—  set  icon  label  to  <label> 

—  turn  OPT  on  (OPT  =  1  =>  pagemode),  e.g.,  \E  [>1;  3;4h 

—  report  OPT;  sends  \E  [>0PT1  or  \E  [>OPTh  for  each  OPT 

—  turn  OPT  off  (OPT  =  1  =>  pagemode),  e.g.,  \E  [>1;  3;41 


As  an  example  of  using  this  facility,  the  following  aliases  can  be  put  into  your  “/.eshre  file; 

#  dynamically  set  the  name  stripe  of  the  tool; 
alias  header  ’echo  -n  ** *  []  1\  1  *"  [\"  * 

#  dynamically  set  the  label  on  the  icon: 
alias  Iheader  ’echo  -n  " “ [] L\ f [X"* 

#  dynamically  set  the  image  on  the  icon: 
alias  icon  ’echo  -n  ”'' [] IXI*”  [X"' 
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A  sample  .ttyswrc  file  follows: 

# 

#  ttysubwindow  startup  file 

# 

set  pagemode 

#Top: 


mapo 
#  Close: 

T1 

\E[5t 

mapo 
#  Move: 

T2 

\E(2t 

mapo 
#  Stretch: 

T3 

\E[3t 

mapo 
#  Bottom: 

T4 

\E[4t 

mapo 
#  Refresh: 

T5 

\E  [6t 

mapo 

T6 

\E[7t 

#  Move  (non-interactive)  to  top  left: 

mapo 

T7 

\E [3;l;lt 

#  stretch  in  chars  (non-interactive)  to  half  high: 

mapo 

T8 

\E[8;10;80t: 

#  Stretch  in  chars  (non-interactive)  to  normal  size: 

mapo 

T9 

\E[8;34;80t 

#  Commands  (very  left  keys,  not  setup): 

map! 

L3 

jobs 

mapi 

L5 

mail 

map! 

L7 

Is  -F 

mapi 
#  Editing: 

L9 

moro  «rrs 

#  Bracket  word 

in  italic  escapes  while  in  vi: 

mapi 

R4 

i\fIEea\fPE 

#  Bracket  word 

in  bold  escapes  while  in  vi: 

mapi 
#  Mail: 

R5 

i\fBEea\fPE 

mapi 

R1 

dt 

mapi 

R2 

s  +planning\ndt\n 

mapi 

R3 

s  +bugs\ndt\n .  sp 

SelectlonB 

Terminal  subwindows  support  a  facility  called  selection,  which  provides  for  limited  inter-tooI 
communication  and  mouse-oriented  text  manipulation.  A  selection  is  a  span  of  characters  which 
you  can  manipulate.  To  make  a  selection: 

•  Press  the  select  (left)  mouse  button  while  the  tip  of  the  cursor  is  over  the  desired  character. 
Your  selection  becomes  highlighted.  This  feedback  helps  you  see  what  you’re  doing.  Any  pre¬ 
vious  selections  are  de-selected;  the  highlighting  around  the  old  selection  disappears.  Move 
the  mouse  with  the  select  button  down,  and  the  selection  changes.  Release  the  select  button 
to  complete  the  selection. 

•  Press  the  adjust  (middle)  mouse  button  down  and  move  the  mouse  to  change  the  span  of 
characters  that  you  select.  Release  the  button.  All  characters,  from  the  one  you  originally 
selected  through  the  one  indicated  when  you  released  adjust,  are  selected.  The  highlighting 
indicating  the  selection  adjusts  to  reflect  its  new  contents. 
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You  can  also  adjust  your  selection  by  multi-clicking.  For  example,  if  you  select  a  character  and 
then  click  the  left  or  middle  mouse  button  over  it  within  .5  seconds,  the  highlighting  adjusts  to 
select  a  word.  Click  again  within  .5  seconds,  and  the  highlighting  adjusts  to  select  a  line.  Click 
yet  again,  and  the  highlighting  now  shows  you  selected  a  paragraph.  Click  one  more  time,  and 
the  selection  shrinks  back  to  the  original  character  you  selected. 

You  can  only  select  characters  which  are  displayed  in  a  terminal  subwindow.  You  can  select 
characters  obscured  by  another  window  if  they  lie  between  the  characters  you  chose  as  the  end¬ 
points  to  the  selection. 

The  highlighting  indicating  the  selection  vanishes  if: 

•  you  move  the  cursor  out  of  the  subwindow  which  holds  the  selection, 

•  you  type  any  key,  or 

•  any  new  output  is  written  to  the  window  which  holds  the  selection. 

However,  even  if  the  selection  highlighting  disappears,  the  selection  still  exists.  You  can  use  it 
until  you  explicitly  make  another  selection.  The  fact  that  the  selection  highlighting  disappears  in 
these  circumstances  reflects  an  incomplete  selection  implementation. 

To  manipulate  your  selection,  press  the  menu  button  over  the  terminal  subwindow.  A  ttysw  menu 
appears  with  the  menu  items  discussed  below: 

Stuff  Select  Stuff,  and  the  characters  in  the  selection  are  copied  to  the  window  as  though  they 
had  been  typed  at  the  keyboard.  The  window  in  which  you  invoke  Stuff  does  not  have 
to  be  the  same  as  the  one  in  which  you  made  the  selection.  You  can  copy  text  between 
windows  with  this  facility. 

If  you  are  an  expert  user,  you  may  want  to  accelerate  the  Stuff  process.  If  you  hold 
down  the  shift  key  while  you  press  the  right  mouse  button,  you  can  stuff  a  selection 
without  selecting  Stuff  from  the  menu. 

Page  Mode  On 

Select  Page  Mode  On  to  prevent  voluminous  tty  subwindow  output  from  scrolling  off  the 
screen.  Page  Mode  can  save  you  from  redoing  a  command  with  a  pipe  to  more  in  such 
cases. 

When  Page  Mode  is  on,  a  tiny  stop  sign  appears  on  the  screen  when  a  command  gen¬ 
erates  a  screenful  of  output.  To  restart  output,  type  any  key,  or  select  the  Continue 
menu  item  discussed  below. 

Page  Mode  Off 

After  you  turn  Page  Mode  on,  you  can  select  Page  Mode  Off  to  turn  it  off. 

Continue 

Select  Continue  to  restart  output  halted  by  Page  Mode. 

You  can  use  the  selection  mechanism  for  building  up  complex  command  sequences  and  to  avoid 
repetitive  keyboard  input.  Selection  facilities  will  be  expanded  in  future  releases. 


Other  Aspects  of  Terminal  Emulators 

Currently,  only  shelltool  and  gfxtool  contain  terminal  emulator  subwindows.  When  you  call  one  of 
these  tools  with  command  line  arguments,  any  arguments  not  speciflc  to  the  tool  pass  to  the  ter¬ 
minal  emulator.  The  terminal  emulator  runs  the  program  named  by  the  first  of  these  arguments. 
If  you  don’t  give  any  arguments,  then  the  terminal  emulator  runs  the  program  described  by  your 
SHELL  environment  value.  If  this  environment  value  is  not  available,  then  /hin/sh  is  run.  Note: 
To  run  a  C  shell  using  its  -c  option  in  either  of  these  tools,  you  must  explicitly  specify  csh  -c  on 
the  command  line  when  you  start  up  the  tool. 
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Start-up  Processing;  The  \Buntools^  File 

suntools  can  set  up  a  predefined  arrangement  of  windows  for  you  when  it  starts  up.  It  does  this 
by  reading  the  file  .suntools  in  your  home  directory  and  following  the  instructions  there.  The  — • 
flag  on  the  command  line  indicates  that  suntools  should  read  an  alternative  file.  The  — n  switch 
suppresses  this  start-up  processing  altogether. 

Each  line  in  the  file  is  a  command  line  corresponding  to  a  tool  to  be  started  up.  These  command 
lines  are  similar  to  those  given  to  a  shell,  but  no  special  character  interpretation  is  performed. 
Use  the  generic  tool  arguments  to  place  the  tool  on  the  screen  (see  Generic  Tool  Arguments). 
Comment  lines  are  preceded  by  a  #. 

For  example: 

shelltool  -C  -Wi 
shell tool 
clocktool  -Wi 

starts  up  a  shelltool  as  the  console  in  its  iconic  form,  a  shelltool  to  be  used  for  interactive  com¬ 
mand  input  and  a  clocktool,  also  in  its  iconic  form.  Note  that  the  system  assigns  the  positions  of 
windows  and  icons  in  this  case,  since  no  positioning  arguments  were  given. 

As  an  alternative,  a  command  line  may  be  a  string  followed  by  9  decimal  numbers,  as  follows: 
path  nl  nt  nw  nh  il  it  iw  ih  I  args 

where  path  is  the  file  name  of  the  tool  to  be  run,  nl,  nt,  nw,  and  nh  are  decimal  numbers  which 
define  the  window  for  the  normal  (open)  tool,  as  left  edge,  top  edge,  width,  and  height;  ;7,  it,  iw, 
and  ih  are  the  same  for  the  iconic  form  of  the  tool;  and  /  is  a  boolean  flag  which  should  be  non¬ 
zero  if  the  tool  is  to  be  started  in  its  iconic  form.  The  remainder  of  the  line  is  passed  to  the  the 
program  running  in  the  window  as  command-line  arguments.  The  origin  (0,0)  is  the  upper  left- 
hand  corner  of  the  screen.  If  a  size  parameter  is  equal  to  —1  then  the  Root  Manager  assigns  an 
appropriate  value. 

•  You  can  include  comments  lines  in  a  .suntools  file  by  preceding  them  with  a  #. 

•  You  can  place  command  lines  in  a  .suntools  file,  but  no  interpretation  ala  shell  is  done.  You 
can  combine  this  facility  with  the  generic  command  line  tool  arguments  to  place  tools. 

Consider  a  .suntools  file  containing: 


shelltool 

0 

72 

-1 

728 

4 

4 

64 

64 

0  vi  $HOME/sked 

shelltool 

372 

0 

-1 

792 

-1 

-1 

64 

64 

0  -C 

clocktool 

4 

4 

180 

40 

232 

4 

64 

64 

1 

This  starts  suntools  with  three  tools  active: 

•  A  shelltool  in  a  window  38  by  80  characters  (in  the  default  font).  It  comes  up  in  the  lower  left 
corner  of  the  screen,  which  leaves  enough  space  above  it  to  fit  some  icons.  The  shelltool  is 
running  the  editor  vi  on  a  file  named  ‘sked*  in  your  home  directory.  The  string  ‘vi 
$HOME/sked’  passes  as  a  command  to  be  executed  by  the  shell  running  in  the  tool.  When 
this  shell  becomes  iconic,  it  moves  to  the  upper  left  corner  of  the  screen. 

•  Another  shelltool  extends  nearly  the  full  height  of  the  screen  (48  lines),  and  butts  against  the 
right  edge.  The  system  places  its  icon  when  this  shell  becomes  iconic.  The  shell  is  ready  for 
your  input  as  soon  as  it  appears  on  the  screen.  Note,  however,  that  all  your  messages  are 
directed  to  this  console  shell.  If  you  hate  being  interrupted  by  biff,  you  should  either  add 
another  shell  to  your  .suntools  file,  or  plan  to  start  another  shell  in  which  to  work  as  soon  as 
Suntools  comes  up  on  the  screen. 

•  A  clocktool  starts  out  iconic,  about  a  quarter  of  the  way  across  the  top  of  the  screen. 

The  program  toolplaces  in  the  directory  /usr/bin  can  help  you  construct  the  .suntools  file;  it 

writes  a  description  of  the  windows  that  exist  at  its  run  time  on  the  standard  output. 
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Customizing  the  Root  Manager  Menu 

A  file  in  /usr/lib  called  ”rootmenu”  contains  a  description  of  the  menu  displayed  over  the  gray 
root  window.  Setting  the  ROOTMENU  parameter  in  your  environment  to  another  file  changes 
the  place  from  which  the  menu  description  is  gleaned.  You  can  customize  the  menu  by  modify¬ 
ing  the  file.  Lines  in  the  file  start  with  the  string  to  display  in  the  menu  followed  by  a  command 
(strings  with  embedded  blanks  are  delimited  with  double  quotes).  Here  are  the  commands  that 
you  can  supply.  Comment  lines  start  with  a  #: 

EXIT  Exit  the  suntools  program,  after  user  confirmation.  To  add  this  command,  place  the  line 
Exit  EXIT 

in  the  file. 

REFRESH 

Redraw  the  entire  screen.  To  add  this  command,  place  the  line 
ReDisplay  REFRESH 

in  the  file. 

MENU  Stack  a  menu  on  the  pile  with  the  Suntools  menu.  Get  the  menu  contents  from  the 
filename  that  follows.  Name  the  menu  with  the  string  preceding.  To  add  this  command, 
place  the  line 

”More  Tools**  MENU  /usr/tmp/rootmonutool 

in  the  file. 

Lines  without  recognized  commands  are  treated  as  command  lines  and  executed: 

Shell  /usr/bin/shelltool 
Lock  /usr/bin/lockscreen  -r 

No  interpretation  ala  shell  is  done. 

Changing  the  System  Font 

The  system  has  a  default  font  built  into  it.  To  use  another  font,  set  the  environment  variable 
DEFAULTJFONT  to  the  name  of  the  file  containing  the  desired  font.  You  have  to  set 
DEFAULTJ'ONT  in  the  shell  from  which  you  invoke  the  program.  You  can  find  a  small 
number  of  valid  alternative  fonts  in  the  directory  fusr/bin/fonte/fizedwidthfonts. 

Multiple/Color  Displays 

The  suntools  program  runs  on  either  a  monochrome  or  color  screen.  Each  screen  on  a  machine 
may  have  its  own  invocation  of  suntools  running  on  it.  The  keyboard  and  mouse  input  devices 
are  shared  among  multiple  screens.  The  mouse  cursor  slides  from  one  screen  to  another  when 
you  move  the  cursor  off  the  edge  of  a  screen. 

A  common  multiple  display  configuration  is  one  monochrome  and  one  color  screen.  You  could 
set  up  an  instance  of  suntools  on  each  screen  in  the  following  way: 

1)  Invoke  suntools  on  the  monochrome  display  by  running  “suntools**.  This  starts  suntools 
on  the  default  frame  buffer  named  fdtujfh. 

2)  In  a  Shelltool,  run  “suntools  -d  /dev/cgoneO’*.  This  starts  suntools  on  a  Sun— 1  color 
screen  named  /dev/cgoneO. 

3)  In  a  Shelltool  on  the  monochrome  screen,  run  “adjacentscreens  /dev/fb  -r  /dev/cgoneO**. 
This  sets  up  cursor  tracking  so  that  the  cursor  slides  from  the  monochrome  screen  to  the 
color  screen  when  you  move  the  cursor  off  the  right  hand  side  of  the  monochrome  screen. 
Similarly,  the  cursor  slides  from  the  color  screen  to  the  monochrome  screen  when  you 
move  the  cursor  off  the  left  hand  side  of  the  color  screen. 
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Getting  Out 

To  exit  any  tool,  invoke  the  Quit  command  in  the  Too!  Manager  Menu  as  described  above.  Typ¬ 
ing  "D  to  the  shell  in  a  terminal  subwindow  also  makes  the  tool  go  away.  To  exit  the  entire 
window  system,  invoke  Exit  in  the  Suntools  menu  as  described  above.  Make  sure  that  all  win¬ 
dows  are  in  a  safe  condition  (for  example,  editors  have  written  out  all  changes)  first. 

You  can  exit  suntools  via  the  keyboard  by  typing  "D  followed  by  "Q.  There  is  no  confirmation. 
This  facility  provides  an  escape  hatch  if  you  inadvertently  start  suntools  when  no  mouse  is 
attached  to  the  system. 

Initialisation 

Before  you  can  run  suntools,  you  have  to  create  the  appropriate  devices  for  it  in  the  /dev  direc¬ 
tory.  You  only  need  to  do  this  once  on  each  machine.  To  create  the  devices, 

•  set  your  user  id  to  root, 

•  change  directory  to  /dev,  and 

•  execute  the  shell  script  ‘MAKEDEV  winO’. 

If  you  tend  to  use  more  than  32  windows,  run  the  script  ‘MAKEDEV  winl’  as  well. 

Suntools  also  needs  the  file  /etc/utmp  to  have  read  and  write  permission  for  all  users.  It  should 
have  been  installed  with  these  permissions,  but  if  not,  you  need  to  use  chmod  to  change  the  per¬ 
missions. 

SEE  ALSO 

Utility  programs  that  run  in  the  SunWindows  environment: 

adjac€ntscreens{l) 

clocktool(l) 

coretool[l) 

dbztool{l) 

fonttoo[{l) 

gfxtool{l) 

icontool{l) 

lock$cre€n{l) 

perfmeter{l) 

perf7non{l) 

skelltool[l) 

tektool{l) 


FILES 

"/.suntools 

"/.ttyswrc 

/usr/bin/suntools 

/  usr/bin/toolplaces 

/usr/lib/fonts/fixedwidthfonts/* 

/usr/lib/rootmenu 

/usr/src/sun/suntool/* 

/dev/winx 

/dev/ptypx 

/dev/ttypz 

/dev/fb 

/dev/kbd 
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/dev/mouse 

/dev/MAKEDEV 

/etc/utmp 

BUGS 

This  release  has  the  following  notable  bugs: 

(1)  Messages  from  the  kernel  ignore  window  boundaries  unless  console  messages  have  been 
redirected,  thus  trashing  the  display.  Recover  from  this  by  invoking  the  ‘ReDisplay  All’ 
item  on  the  Root  Manager  menu.  Then  start  a  ghelltool  with  the  -C  option  to  redirect 
the  console  output. 

(2)  Acceptable  performance  on  realistic  tasks  (such  as  editing  with  vi  while  make  performs  a 
C  compilation)  requires  about  600K  of  available  user  memory.  In  some  cases,  the  kernel 
may  have  to  be  reconfigured  to  make  that  space  available.  See  the  Spslem  Manager'a 
Guide . 
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NAME 

sync  —  update  the  super  block 

SYNOPSIS 

sync 

DESCRIPTION 

Sync  executes  the  sync  system  primitive.  Sync  can  be  called  to  ensure  all  disk  writes  have  been 
completed  before  the  processor  is  halted  in  a  way  not  suitably  done  by  reboot{S)  or  A<i/((8). 

See  sj/nc(2)  for  details  on  the  system  primitive. 

SEE  ALSO 

sync(2),  fsync(2},  halt(8),  reboot(8),  cron(8) 
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NAME 

syslog  ~  make  system  log  entry 
SYNOPSIS 

syslog  [  — p  ]  I  — 1  name  ]  |  — level  |  |  “  ]  (  tnessage  •••  ] 

DESCRIPTION 

S]/$log  sends  the  specified  message  (or  eldin  if  —  is  specified)  as  a  system  log  entry  to  the  syslog 
daemon.  The  log  entry  is  sent  to  the  daemon  on  the  machine  specified  by  the  loghost  entry  in 
the  /etc/ hosts  file. 

OPTIONS 

— p  Syslog  will  log  its  process  id  in  addition  to  the  other  information^ 

—1  name 

The  specified  name  will  be  used  as  the  “ident”  for  the  log  entry. 

-level  The  message  will  be  logged  at  the  specified  level.  The  level  can  be  specified  numerically, 
in  the  range  1  through  9,  or  symbolically  using  the  names  specified  in  the  include  file 
/usr/include/syslog.h  (with  the  leading  LOG_  stripped  off),  “syslog  -HELP”  will  list  the 
valid  symbolic  level  names.  Only  the  superuser  can  make  log  entries  at  levels  less  than 
or  equal  to  SALERT. 

—  Each  line  of  the  standard  input  is  sent  as  a  log  entry. 


FILES 

/usr/etc/in.syslog  syslog  daemon 
/usr/include/syslog.h  for  names  of  logging  levels 

SEE  ALSO 

syslog(3),  syslog(8) 
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NAME 

tail  —  display  the  last  part  of  a  file 
SYNOPSIS 

t^l  [  inumicrl Ibc ]  [fr  I  ]  [  file  j 
DESCRIPTION 

Tail  copies  the  named  file  to  the  standard  output  beginning  at  a  designated  place.  If  no  file  is 
named,  the  standard  input  is  used. 

OPTIONS 

Options  are  all  jammed  together,  not  specified  separately  with  their  own  —  signs. 

-tnumber 

Begin  copying  at  distance  +  n«m6er  from  the  beginning  of  the  file.  Number  is  counted  in 
units  of  lines,  blocks  or  characters,  according  to  the  appended  option  I,  b,  or  c.  When  no 
units  are  specified,  counting  is  by  lines, 

’—number 

Begin  copying  at  distance  —number  from  the  end  of  the  file.  Number  is  counted  in  units 
of  lines,  blocks  or  characters,  according  to  the  appended  option  1,  b,  or  c.  When  no  units 
are  specified,  counting  is  by  lines. 

r  Copy  lines  from  the  end  of  the  file  in  reverse  order.  The  default  for  p  is  to  print  the 

entire  file  this  way. 

f  Follow  the  file  as  it  grows,  that  is,  don’t  quit  at  end  of  file,  but  rather  wait  and  try  to 

read  repeatedly  in  hopes  that  the  file  will  grow. 

SEE  ALSO 

dd(i) 

BUGS 

Tails  relative  to  the  end  of  the  file  are  treasured  up  in  a  buffer,  and  thus  are  limited  in  length. 
Various  kinds  of  anomalous  behavior  may  happen  with  character  special  files. 
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NAME 

talk  —  talk  to  another  user 
SYNOPSIS 

talk  person  [  ttyname  j 
DESCRIPTION 

Talk  is  a  visual  communication  program  which  copies  lines  from  your  terminal  to  that  of  another 
user. 

If  you  wish  to  talk  to  someone  on  your  own  machine,  then  person  is  just  the  person’s  login  name. 
If  you  wish  to  talk  to  a  user  on  another  host,  then  person  is  of  the  form  : 
kostluser  or 
host.user  or 
hostiuser  or 
user@host 

though  u$er@ko$t  is  perhaps  preferred. 

If  you  want  to  talk  to  a  user  who  is  logged  in  more  than  once,  the  ttyname  argument  may  be 
used  to  indicate  the  appropriate  terminal  name. 

When  first  called,  talk  sends  the  message: 

Message  from  TalkDaemon@his_machine... 
talk:  connection  requested  by  your_name@your_machine. 
talk:  respond  with:  talk  your_name@your_machine 
to  the  user  you  wish  to  talk  to.  At  this  point,  the  recipient  of  the  message  should  reply  by  typ¬ 
ing: 

tutorial%  talk  your_jianie@your_machinc 

It  doesn’t  matter  from  which  machine  the  recipient  replies,  as  long  as  their  login-name  is  the 
same.  Once  communication  is  established,  the  two  parties  may  type  simultaneously,  with  their 
output  appearing  in  separate  windows.  Typing  control-L  redraws  the  screen,  while  your  erase, 
kill,  and  word  kill  characters  will  work  in  talk  as  normal.  To  exit,  just  type  your  interrupt  char¬ 
acter;  talk  then  moves  the  cursor  to  the  bottom  of  the  screen  and  restores  the  terminal. 

Permission  to  talk  may  be  denied  or  granted  by  use  of  the  command.  At  the  outset 

talking  is  allowed.  Certain  commands,  in  particular  nroJf(l)  and  pr(l)  disallow  messages  in  order 
to  prevent  messy  output. 

FILES 

/etc/hosts  to  find  the  recipient’s  machine 

/etc/utmp  to  find  the  recipient’s  tty 

SEE  ALSO 

mesg(l),  who(l),  mail(l),  write(l) 
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NAME 

tar  —  tape  archiver 

SYNOPSIS 

tar  “txpuc[ovwfbImhpB0-0!|  [  tarfile  ]  [  blocksize  ]  filel  file2  ...  — C  dir  filen  ... 

DESCRIPTION 

Tar  saves  and  restores  multiple  files  on  a  single  tarfile  (usually  a  magnetic  tape,  but  it  can  be  any 
file).  Tar's  actions  are  controlled  by  its  first  argument,  the  key,  a  string  of  characters  containing 
exactly  one  function  letter  from  the  set  rxtuc  and  one  or  more  optional  function  modifiers. 
Other  arguments  to  tar  are  file  or  directory  names  specifying  which  files  to  dump  or  restore.  In 
all  cases,  appearance  of  a  directory  name  refers  to  the  files  and  (recursively)  subdirectories  of 
that  directory. 

FUNCTION  LETTERS 

r  Write  the  named  files  on  the  end  of  the  tarfile.  Note  that  this  option  does  not  work  with 
quarter-inch  archive  tapes. 

X  Extract  the  named  files  from  the  tarfile.  If  the  named  file  matches  a  directory  whose  con¬ 
tents  had  been  written  onto  the  tape,  this  directory  is  (recursively)  extracted.  The  owner, 
modification  time,  and  mode  are  restored  (if  possible).  If  no  file  argument  is  given,  the  entire 
content  of  the  tape  is  extracted.  Note  that  if  multiple  entries  specifying  the  same  file  are  on 
the  tape,  the  last  one  overwrites  all  earlier  versions. 

t  List  the  names  of  the  specified  files  each  time  they  occur  on  the  tarfile.  If  no  file  argument  is 
given,  all  of  the  names  on  the  tarfile  are  listed. 

u  Add  the  named  files  to  the  tarfile  if  they  are  not  there  or  have  been  modified  since  last  put  on 
the  tarfile.  Note  that  this  option  does  not  work  with  quarter-inch  archive  tapes. 

c  Create  a  new  tarfile  and  write  the  named  files  onto  it. 

FUNCTION  MODIFIERS 

Select  an  alternate  drive  on  which  the  tape  is  mounted.  The  default  is  drive  0  at  1500  bpi, 
which  is  normally  /dev/rmtS, 

t  Use  the  next  argument  as  the  name  of  the  archive  instead  of  fdev/rmtS,  If  the  name  of  the 
file  is  tar  writes  to  standard  output  or  reads  from  standard  input,  whichever  is  appropri¬ 
ate.  Thus,  tar  can  be  used  as  the  head  or  tail  of  a  filter  chain.  Tar  can  also  be  used  to  copy 
hierarchies  with  the  command: 

tutorial%  cd  fk'omdlr;  tar  cf  —  .  }  (cd  todlr;  tar  xfBp  — ) 

o  Suppress  information  specifying  owner  and  modes  of  directories  which  tar  normally  places  in 
the  archive.  Such  information  makes  former  versions  of  tar  generate  an  error  message  like: 

‘<name>/:  cannot  create’ 
when  they  encounter  it. 

V  Normally  ^or  does  its  work  silently;  the  v  (verbose)  option  displays  the  name  of  each  file  tar 
treats,  preceded  by  the  function  letter.  When  used  with  the  t  function,  v  displays  the  tarfile 
entries  in  a  form  similar  to  la  —1. 

w  Wait  for  user  confirmation  before  taking  the  specified  action.  If  you  use  w,  tar  displays  the 
action  to  be  taken  followed  by  the  file  name,  and  then  waits  for  a  *y*  response  to  proceed.  No 
action  is  taken  on  the  named  file  if  you  type  anything  other  than  a  line  beginning  with  ‘y’. 

b  Use  the  next  argument  as  the  blocking  factor  for  tape  records.  The  default  blocking  factor  is 
20  blocks.  The  block  size  is  determined  automatically  when  reading  tapes  (key  letters  x  and 
t).  This  determination  of  the  blocking  factor  may  be  fooled  when  reading  from  a  pipe  or  a 
socket  (see  the  B  key  letter  below).  The  maximum  blocking  factor  is  determined  only  by  the 
amount  of  memory  available  to  the  program  at  the  time  it  runs.  Larger  blocking  factors 
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result  in  better  throughput,  longer  blocks  on  nine-track  tapes,  and  better  media  utilization. 

1  Display  error  messages  if  all  links  to  dumped  files  cannot  be  resolved.  If  1  is  not  used,  no 
error  messages  are  printed. 

m  Do  not  restore  modification  times  of  extracted  files.  The  modification  time  will  be  the  time  of 
extraction, 

h  Follow  symbolic  links  as  if  they  were  normal  files  or  directories.  Normally,  tar  does  not  follow 
symbolic  links. 

p  Restore  the  named  files  to  their  original  modes,  ignoring  the  present  umask(2).  Setuid  and 
sticky  information  are  also  restored  if  you  are  the  super-user.  This  option  is  only  useful  with 
the  X  key  letter. 

B  Force  tar  to  perform  multiple  reads  (if  necessary)  so  as  to  read  exactly  enough  bytes  to  fill  a 
block.  This  option  exists  so  that  tar  can  work  across  the  Ethernet,  since  pipes  and  sockets 
return  partial  blocks  even  when  more  data  is  coming. 

i  Ignore  directory  checksum  errors. 

If  a  file  name  is  preceded  by  — C  in  a  c  (create)  or  r  (replace)  operation,  tar  will  perform  a 
chdir{2)  to  that  file  name.  This  allows  multiple  directories  not  related  by  a  close  common  parent 
to  be  archived  using  short  relative  path  names.  For  example,  to  archive  files  from  /usrf  include 
and  from  /etc,  one  might  use: 

tutorial%  tar  c  — C  /usr  include  — C  /etc  • 

If  you  get  a  table  of  contents  from  the  resulting  tarfile,  you  will  see  something  like: 
include/ 
include/a.out.h 

and  all  the  other  files  in  fusr/include 

./ 

./chown 

and  all  the  other  files  in  /etc 

Note  that  the  — C  option  only  applies  to  one  following  directory  name  and  one  following  file 
name. 

EXAMPLES 

Here  is  a  simple  example  using  far  to  create  an  archive  of  your  home  directory  onto  jdevjrmtQ'. 
tutorial%  cd  position  yourself  in  your  home  directory 

tutorial^  tar  cvf  /dev/rmtO  •  create  the  archive 

lots  of  messages  from  tar 

tutorial% 

The  c  option  means  create  the  archive;  the  v  option  makes  tar  tell  you  what  it’s  doing  as  it 
works;  the  f  option  means  that  you  are  specifically  naming  the  file  onto  which  the  archive  should 
be  placed  {/dev/rmtO  in  this  example). 

Now  you  can  read  the  table  of  contents  from  the  archive  like  this: 

tutorial%  tar  tvf  /dev/rmtO  display  table  of  contents  of  the  archive 

lots  of  messages  from  tar 

tutoria!% 

Where  the  t  option  is  for  displaying  the  table-of-contents  of  the  archive.  You  can  extract  files 
from  the  archive  like  this: 

tutorial^  tar  xvf  /dev/rmtO  extract  files  from  the  archive 

lots  of  messages  from  tar 

tutorial% 
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Where  the  x  option  is  for  extracting  files  from  the  archive. 

If  there  are  multiple  archive  files  on  a  tape,  each  is  separated  from  the  following  one  by  an  end- 
of-file  marker.  Tar  does  not  read  the  end-of-file  mark  on  the  tape  after  it  finishes  reading  an 
archive  file  because  tar  looks  for  a  special  header  to  decide  when  it  has  reached  the  end  of  the 
archive.  Now  if  you  try  to  use  tar  to  read  the  next  archive  file  from  the  tape,  tar  doesn’t  know 
enough  to  skip  over  the  end-of-file  mark  and  tries  to  read  the  end-of-file  mark  as  an  archive 
instead.  The  result  of  this  is  an  error  message  from  tar  to  the  effect: 
tar:  biocksize=0 

This  means  that  to  read  another  archive  from  the  tape,  the  user  must  skip  over  the  end-of-file 
marker  before  starting  another  tar  command.  You  can  achieve  this  via  the  mt  command,  as 
shown  in  the  example  below.  Assume  that  you  are  reading  from  f  devfnrmtO. 

tutorial%  tar  xvfi>  /dev/nrmtO  read  first  archive  from  tape 
iota  of  messages  from  tar 

tutorial%  mt  fsf  1  skip  over  the  end-of-file  marker 
tutorial%  tar  xvfp  /dev/nrmtO  read  second  archive  from  tape 
lots  of  messages  from  tar 

tutorial% 

Finally,  here  is  an  example  using  tar  to  transfer  files  across  the  Ethernet.  First,  here  is  how  to 
dump  files  from  the  local  machine  (tutorial)  to  a  tape  on  a  remote  system  (krypton): 

tutorial%  tar  cvfb  —  20  files  |  rsh  krypton  dd  of=/dev/rmtO  ob8»20b 
lots  of  messages  from  tar 

tutorlaI% 

In  the  example  above,  we  are  creating  a  tarfile  with  the  c  key  letter,  asking  for  verbose  output 
from  tar  with  the  v  option,  specifying  the  name  of  the  output  tarfile  via  the  f  option  (the  stan¬ 
dard  output  is  where  the  tarfile  appears,  as  indicated  by  the  —  sign),  and  specifying  the  blocksize 
(20)  with  the  b  option.  If  you  want  to  change  the  blocksize,  you  must  change  the  blocksize  argu¬ 
ments  both  on  the  tar  command  and  on  the  dd  command. 

Now,  here  is  how  to  use  tar  to  get  files  from  a  tape  on  the  remote  system  (krypton)  back  to  the 
local  system  (tutorial): 

tutorial%  rsh  krypton  dd  If— /dev/rmtO  bB=20b  }  tstf  xvBfb  —  20  files 
lots  of  messages  from  tar 

tutorial% 

In  the  example  above,  we  are  extracting  from  the  tarfile  with  the  x  key  letter,  asking  for  verbose 
output  from  tar  with  the  v  option,  specifying  the  name  of  the  input  tarfile  via  the  f  option  (the 
standard  input  is  where  the  tarfile  appears,  as  indicated  by  the  —  sign),  and  specifying  the  block- 
size  (20)  with  the  b  option. 

FILES 

/dev/rmt?  half-inch  magnetic  tape  interface 
/dev/rar?  quarter-inch  magnetic  tape  interface 
/dev/rst?  SCSI  tape  interface 
/tm  p/tar* 

SEE  ALSO 

tar(5),  cpio(l),  dump(8),  restore(8) 

DIAGNOSTICS 

Complains  about  bad  key  characters  and  tape  read/write  errors. 

Complains  if  enough  memory  is  not  available  to  hold  the  link  tables. 

BUGS 
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Neither  the  r  option  nor  the  u  option  can  be  used  with  quarter-inch  archive  tapes,  since  these 
tape  drives  cannot  backspace. 

There  is  no  way  to  ask  for  the  n-th  occurrence  of  a  file. 

Tape  errors  are  handled  ungracefully. 

The  u  option  can  be  slow. 

There  is  no  way  to  selectively  follow  symbolic  links. 
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NAME 

tbl  —  format  tables  for  nroff  or  troff 
SYNOPSIS 

tW  [  —ms  j  [  —mm  ]  [  files  | 

DESCRIPTION 

Tbl  is  a  preprocessor  for  formatting  tables  for  nroff  or  troff(i).  The  input  files  are  copied  to  the 
standard  output,  except  that  lines  between  .TS  and  •TE  command  lines  are  assumed  to  describe 
tables  and  are  reformatted.  Details  are  given  in  the  tbl{l)  reference  manual. 

If  no  arguments  are  given,  tbl  reads  the  standard  input,  so  tbl  may  be  used  as  a  filter.  When  tbl 
is  used  with  eqn  or  neqn  the  tbl  command  should  be  first,  to  minimize  the  volume  of  data  passed 
through  pipes. 

OPTIONS 

—mi  Copy  the  -ms  macro  package  to  the  front  of  the  output  file. 

—mm  Copy  the  —mm  macro  package  to  the  front  of  the  output  file. 

EXAMPLE 

As  an  example,  letting  \t  represent  a  tab  (which  should  be  typed  as  a  genuine  tab)  the  input 

.TS 
css 
CCS 
c  c  c 
1  n  n. 

Household  Population 

Town\tHouseholds 

\tNumber\tSize 

Bedminster\t789\t3.26 

Bernards  Twp,\t3087\t3.74 

Bernardsville\t2018\t3.30 

Bound  Brook\t3425\t3.04 

Branchburg\tl644\tk49 

Bridgewater\t7897\t3.81 

Far  Hills\t240\t3.19 

.TE 

yields 


Household  Population 


Town 

Households 

Number 

Size 

Bedminster 

789 

3.26 

Bernards  Twp. 

3087 

3.74 

Bernardsville 

2018 

3.30 

Bound  Brook 

3425 

3.04 

Branchburg 

1644 

3.49 

Bridgewater 

7897 

3.81 

Far  Hills 

240 

3.19 

SEE  ALSO 

troff(l),  eqn(l) 

Formatting  Tables  with  tbl  in 

Editing  and  Text  Processing  on  the  Sun  Workstation. 

o 
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NAME 

tcov  —  construct  test  coverage  analysis  and  statement- by-statement  profile 
SYNOPSIS 

tcov  [  —a  j  [  — n  1  file.c 
DESCRIPTION 

Tcov  produces  a  test  coverage  analysis  and  statement- by-statement  profile  of  a  C  program.  The 
coverage  data  for  routines  contained  in  a  file  named  filtmC  is  taken  from  the  corresponding  file^d 
produced  by  running  the  C  compiler  cc(l)  with  the  —a  option.  An  annotated  listing  of  the  pro¬ 
gram  with  coverage  data  is  placed  in  fileJcov.  Each  straight-line  segment  of  code  (or  each  line  if 
the  —a  option  to  tcov  is  specified)  is  prefixed  with  the  number  of  times  it  has  been  executed;  lines 
which  have  not  been  executed  are  prefixed  with  #####. 

Note  that  the  profile  produced  includes  only  the  number  of  times  each  statement  was  executed, 
not  execution  times;  to  obtain  times  for  routines  use  gprof{l)  or  prof{l). 

Test  coverage  data  from  several  runs  will  accumulate  in  the  *d  files. 

OPTIONS 

—a  display  an  execution  count  for  each  statement;  if  —a  is  not  specified,  an  execution  count 
is  displayed  only  for  the  first  statement  of  each  straight-line  segment  of  code. 

— n  display  table  of  the  line  numbers  of  the  n  most  frequently  executed  statements  and  their 

execution  counts, 

SEE  ALSO 

cc(l),  prof(l),  gprof(l) 

FILES 

file.c 
file.d 
file  .tcov 

/usr/bin/count 
/usr/lib/bbjink.o 

BUGS 

The  analyzed  program  must  call  exit{2)  or  return  normally  for  the  coverage  information  to  be 
saved  in  the  file. 

‘Premature  end  of  file’  message  for  routine  containing  no  statements. 


input  C  program  file 

input  test  coverage  data  file 

output  test  coverage  analysis  listing  file 

preprocessor  for  test  coverage  analysis 

startoff  and  exit  routines  for  test  coverage  analysis 
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NAME 

tee  —  copy  standard  output  to  many  files 

SYNOPSIS 

tee  I  — I  I  (  — a  ]  I  file  i 
DESCRIPTION 

Tee  transcribes  the  standard  input  to  the  standard  output  and  makes  copies  in  the  files, 
OPTIONS 

— !  Ignore  interrupts. 

—a  Append  the  output  to  the  files  rather  than  overwriting  them. 
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NAME 

tektool  —  Tektronix  4014  terminal  emulator  tool 
SYNOPSIS 

tektool  [— f  fontdir  J  [  — a[lcdeglce]  ]  [  — c  command  line  |  (  — r  command  line  | 

DESCRIPTION 

Tektool  emulates  a  Tektronix  4014  terminal  with  the  enhanced  graphic  module.  It  does  this  in 
much  the  same  way  as  shelltool  (see  a«nfoo/s(l))  emulates  a  regular  glass  tty.  When  tektool  is 

invoked,  a  command  (usually  a  shell)  is  started  up,  its  output  and  input  are  connected  to  the 

emulator,  and  a  new  window  is  formed.  The  default  window  is  the  entire  screen.  When  the 
emulator  is  running,  buttons  TF(1)  through  TF(4),  (usually  function  keys  1-4  (see  kbd{b))  have 
special  meaning. 

TF(1)  Unshifted,  this  is  the  4014  PAGE  button.  Shifted,  this  is  the  4014  RESET  button. 

TF(2)  Set  local  mode. 

TF(3)  Set  on-line  mode. 

TF(4)  Copy  screen.  The  raster  image  {/usr/include/raeterfile^h)  of  the  4014  screen  is  piped  to 

a  command  found  in  the  TEKCOPY  environment  variable.  The  copy  button  is 

unaffected  by  window  manipulations,  and  will  transmit  the  contents  of  the  4014  screen 
only. 

When  in  graphics  input  (GIN)  mode  and  the  4014  crosshairs  are  visible,  the  left  hand  mouse  but¬ 
ton  may  be  used  as  the  space  bar  to  terminate  GIN  mode. 

OPTIONS 

— f  fontdir 

Look  for  fonts  in  the  directory  specified  by  fontdir.  The  fonts  must  be  called  tekfontO 
through  tekfontZ.  Fonts  must  be  in  u/(?n^(5)  format.  If  this  option  is  not  given,  the  font 
directory  is  obtained  from  the  TEKFONTS  environment  variable  (if  it  exists).  If  no  font  direc¬ 
tory  is  specified,  /usr/libf fonts  is  used, 

— s 

Specifies  the  Tektronix  4014  strap  options  with  the  following  modifiers: 

1  Received  linefeeds  also  generate  carriage  returns, 
c  Received  carriage  returns  also  generate  linefeeds, 
d  Received  DEL  characters  are  used  as  low  order  Y  axis  addresses, 
e  Echo  keyboard  input. 

g  Graphic  input  mode  (GIN)  terminator  specification.  If  this  strap  is  followed  by  a  c,  GIN 
mode  data  is  terminated  by  a  carriage  return.  If  it  is  followed  by  a  e,  GIN  mode  data  is 
terminated  by  a  carriage  return  followed  by  an  EOT  character.  If  this  strap  is  not 
present,  no  characters  are  sent  after  GIN  mode  data. 

If  the  — s  option  is  not  given,  the  environment  is  searched  for  the  TEKSTRAPS  variable  which 
provides  the  modifiers.  If  no  straps  are  specified  the  d  strap  is  assumed. 

— c  command  line 

Take  terminal  emulator  input  from  a  shell  which  in  turn  runs  the  command  line  following  the 
— c  option. 

— -r  command  line 

Run  command  line  to  provide  input  to  the  terminal  emulator.  This  must  be  the  last  option, 
since  the  remainder  of  the  arguments  are  used. 

CAVEATS 

Like  all  4014  emulators,  this  probably  doesn’t  duplicate  every  nuance  of  the  4014.  For  instance, 
certain  programs  redraw  stuff  already  on  the  screen  in  order  to  highlight  things  with  the  storage 
flash.  Needless  to  say,  this  won’t  work  here  (however  if  you  redraw  it  in  writethru  mode  it  will 
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work!!).  Also,  even  though  the  emulator  supports  the  full  4096  address  of  the  4014,  it  cannot 
display  this  on  the  screen.  All  points  will  be  rounded  to  the  nearest  available  pixel.  This  may 
cause  some  funny  effects. 

The  tektool  window  may  be  treated  just  like  other  windows;  it  can  be  overlaid,  moved,  reshaped 
etc.  However,  when  the  window  is  reshaped,  the  contents  will  not  scale. 

FILES 

/usr/lib/fonts/tekfontlO-3] 

SEE  ALSO 

suntools(l) 

Tektronix  4014  and  4014-1  Computer  Display  Terminal  User’s  Manual  (070-1647-00) 

BUGS 

(1) 

(2) 

(3) 

(4) 

(5) 

(6) 

(7) 


Special  point  plot  mode  is  not  supported. 

Z  axis  stuff,  except  for  defocusing,  is  not  supported. 

Defocused  alpha  characters  are  not  supported. 

The  fonts  need  help. 

Needs  scroll  bars  from  the  window  system  to  make  the  whole  4014  screen  accessable 
from  a  small  window. 

There  are  no  user  prompts  for  waiting  (for  copy)  and  to  remind  people  about  the  func¬ 
tion  keys. 

The  current  implementation  seems  to  have  an  effective  baud  rate  of  between  4800  and 
9600. 
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NAME 

telnet  -  user  interface  to  the  TELNET  protocol 

SYNOPSIS 

telnet  (  host  |  port  |  | 

DESCRIPTION 

Telnet  communicates  with  another  host  using  the  TELNET  protocol.  If  telnet  is  invoked  without 
arguments,  it  enters  command  mode,  indicated  by  its  prompt  (“telnet>”).  In  this  mode,  it 
accepts  and  executes  the  commands  listed  below.  If  it  is  invoked  with  arguments,  it  performs  an 
open  command  (see  below)  with  those  arguments. 

Once  a  connection  has  been  opened,  telnet  enters  input  mode.  In  this  mode,  text  typed  is  sent  to 
the  remote  host.  To  issue  telnet  commands  when  in  input  mode,  precede  them  with  the  telnet 
^‘escape  character”  (initially  “"|”).  When  in  command  mode,  the  normal  terminal  editing  con¬ 
ventions  are  available. 

TELNET  COMMANDS 

The  following  commands  are  available.  Only  enough  of  each  command  to  uniquely  identify  it 
need  be  typed. 

open  host  [  port  | 

Open  a  connection  to  the  named  host.  If  the  no  port  number  is  specified,  telnet  will 
attempt  to  contact  a  TELNET  server  at  the  default  port.  The  host  specification  may  be 
either  a  host  name  (see  Ao5/s(5))  or  an  Internet  address  specified  in  the  “dot  notation”. 

close  Close  a  TELNET  session  and  return  to  command  mode. 

quit  Close  any  open  TELNET  session  and  exit  telnet. 

z  Suspend  telnet.  This  command  only  works  when  the  user  is  using  the  csA(l). 

escape  [  escape-ckar  | 

Set  the  telnet  “escape  character”.  Control  characters  may  be  specified  as  followed 
by  a  single  letter;  e.g.  “controLX”  is  “"X”. 

status  Show  the  current  status  of  telnet.  This  includes  the  peer  one  is  connected  to,  as  well  as 
the  state  of  debugging. 

options 

Toggle  viewing  of  TELNET  options  processing.  When  options  viewing  is  enabled,  all  TEL¬ 
NET  option  negotiations  will  be  displayed.  Options  sent  by  telnet  are  displayed  as 
“SENT”,  while  options  received  from  the  TELNET  server  are  displayed  as  “RCVD”. 

crmod  Toggle  carriage  return  mode.  When  this  mode  is  enabled  any  carriage  return  characters 
received  from  the  remote  host  will  be  mapped  into  a  carriage  return  and  a  line  feed. 
This  mode  does  not  affect  those  characters  typed  by  the  user,  only  those  received.  This 
mode  is  not  very  useful,  but  is  required  for  some  hosts  that  like  to  ask  the  user  to  do 
local  echoing. 

r  [  command  j 

Get  help.  With  no  arguments,  telnet  prints  a  help  summary.  If  a  command  is  specified, 
telnet  will  print  the  help  information  available  about  the  command  only. 

SEE  ALSO 

r!ogin(lC) 

BUGS 

There  is  no  provision  in  the  standard  TELNET  protocol  to  support  "S/"Q  type  commands.  This 
implementation  is  very  simple  because  rlogin{lC)  is  the  standard  mechanism  used  to  communi¬ 
cate  locally  with  hosts. 
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NAME 

test  —  condition  command 

SYNOPSIS 

test  txpr 

DESCRIPTION 

evaluates  the  expression  expr,  and  if  its  value  is  true  then  returns  zero  exit  status;  otherwise, 
a  non  zero  exit  status  is  returned,  test  returns  a  non  zero  exit  if  there  are  no  arguments. 

The  following  primitives  are  used  to  construct  expr. 

“b  file  true  if  the  file  exists  and  is  a  block  special  device. 

— c  file  true  if  the  file  exists  and  is  a  character  special  device. 

— d  file  true  if  the  file  exists  exists  and  is  a  directory. 

— f  file  true  if  the  file  exists  and  is  not  a  directory. 

— g  filt  true  if  the  file  exists  and  is  setgid. 

— h  file  true  if  the  file  exists  and  is  a  symbolic  link. 

— k  file  true  if  the  file  exists  and  is  sticky. 

—1  siring  the  length  of  the  string. 

— n  si  true  if  the  length  of  the  string  si  is  nonzero. 

— r  file  true  if  the  file  exists  and  is  readable. 

— •  file  true  if  the  file  exists  and  has  a  size  greater  than  zero, 

-t  I  fildes  ] 

true  if  the  open  file  whose  file  descriptor  number  is  fildes  (1  by  default)  is  associated 
with  a  terminal  device, 

“W  file  true  if  the  file  exists  and  is  writable. 

— *x  file  true  if  the  file  exists  and  is  executable. 

— *  si  true  if  the  length  of  string  si  is  zero. 

si  =  s2  true  if  the  strings  si  and  sS  are  equal. 

$1  !=  sS  true  if  the  strings  si  and  sS  are  not  equal, 

si  true  if  si  is  not  the  null  string. 

nl  “*eq  n£ 

true  if  the  integers  nl  and  nS  are  algebraically  equal.  Any  of  the  comparisons  — ne, 
— gt,  —ge,  —It,  or  — le  may  be  used  in  place  of  — eq. 

These  primaries  may  be  combined  with  the  following  operators: 

!  unary  negation  operator 

—a  binary  and  operator 

— o  binary  or  operator 

(  earpr  ) 

parentheses  for  grouping. 

— •  has  higher  precedence  than  — o.  Notice  that  all  the  operators  and  flags  are  separate  argu¬ 
ments  to  test.  Notice  also  that  parentheses  are  meaningful  to  the  Shell  and  must  be  escaped. 

SEE  ALSO 

sh(l),  find(l) 
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NAME 

time  —  time  a  command 

SYNOPSIS 

time  [  command  j 

DESCRIPTION 

There  are  two  distinct  versions  of  time:  it  is  built  in  to  the  C-shell,  and  is  an  executable  program 
available  in  /bin/time  when  using  the  Bourne  shell*  In  both  cases,  times  are  displayed  on  the 
diagnostic  output  stream. 

In  the  case  of  the  C-shell,  a  time  command  with  no  command  argument  simply  displays  a  sum¬ 
mary  of  time  used  by  this  shell  and  its  children.  When  arguments  are  given  the  specified  simple 
command  is  timed  and  the  C-shell  displays  a  time  summary  as  described  below  under  the  time 
variable*  If  necessary,  an  extra  shell  is  created  to  print  the  time  statistic  when  the  command 
completes* 

The  default  resource-usage  summary  is  a  line  of  the  form: 

unuMW  S8S,8S  ee:ee  pp%  xzx-^dddk  tii-k-ocoio  mmmpt-^wwvf 
where  uuu.u  is  the  user  time  (U),  e$8.e  is  the  system  time  (S),  ee:ee  is  the  elapsed  time  (E),  pp  is 
the  percentage  of  CPU  time  versus  elapsed  time  (P),  xxx  is  the  average  shared  memory  in  Kilo¬ 
bytes  (X),  ddd  is  the  average  unshared  data  space  in  Kilobytes  (D),  m  and  ooo  are  the  number  of 
block  input  and  output  operations  respectively  (I  and  O),  mmm  is  the  number  of  page  faults  (M), 
and  u;w;is  the  number  of  swaps  (W)* 

The  time  variable  controls  the  display  that  the  C-shell  prints  when  it  times  a  command.  The 
time  variable  can  be  supplied  with  one  or  two  values*  The  first  value  is  a  number  —  n  for 
instance.  The  C-shell  displays  a  resource-usage  summary  for  any  command  running  for  more 
than  n  CPU  seconds.  The  second  value  is  optional  and  is  a  character  string  which  determines 
which  resources  the  user  wishes  displayed.  The  character  string  can  be  any  string  of  text  with 
embedded  control  key-letters  in  it.  A  control  key-letter  is  a  percent  sign  {%)  followed  by  a  single 
upper*ca8€  letter*  To  print  a  percent  sign,  use  two  percent  signs  in  a  row.  Unrecognized  key- 
letters  are  simply  printed.  The  control  key-letters  are: 

D  Average  amount  of  unshared  data  space  used  in  Kilobytes. 

E  Elapsed  (wallclock)  time  for  the  command. 

F  Page  faults. 

I  Number  of  block  input  operations. 

K  Average  amount  of  unshared  stack  space  used  in  Kilobytes. 

M  Maximum  real  memory  used  during  execution  of  the  process. 

O  Number  of  block  output  operations. 

P  Total  CPU  time  —  U  (user)  plus  S  (system)  —  as  a  percentage  of  E  (elapsed) 
time. 

S  Number  of  seconds  of  CPU  time  consumed  by  the  kernel  on  behalf  of  the  user’s 
process. 

U  Number  of  seconds  of  CPU  time  devoted  to  the  user’s  process. 

W  Number  of  swaps. 

X  Average  amount  of  shared  memory  used  in  Kilobytes. 

The  time  command  in  ybin/time’  times  the  given  command,  which  must  be  specified,  that  is, 
command  is  not  optional  as  it  is  in  the  C-shell’s  timing  facility*  When  the  command  is  complete, 
time  displays  the  elapsed  time  during  the  command,  the  time  spent  in  the  system,  and  the  time 
spent  in  execution  of  the  command.  Times  are  reported  in  seconds. 

EXAMPLES 

The  two  examples  here  show  the  differences  between  the  csk  version  of  time  and  the  version  in 
/bin/ time.  The  example  assumes  that  csk  is  the  shell  in  use. 
angel%  time  wc  /u8r/man/m&nl/csh«l 
1876  11223  65895  /usr/man/manl/csh.l 


344 


Last  change:  2  November  1983 


Sun  Release  2,0 


TIME(l) 


USER  COMMANDS 


TIME(l) 


2,7u  0.9s  0:03  91%  3+5k  19+2io  Ipf+Ow 
angel%  /bln/tlme  wc  /uar/man/manl/csh.! 

1876  11223  65895  /usr/man/manl/csh.l 

4.3  real  2.7  user  1.0  sys 
angel% 

BUGS 

Elapsed  time  is  accurate  to  the  second,  while  the  CPU  times  are  measured  to  the  50th  second. 
Thus  the  sum  of  the  CPU  times  can  be  up  to  a  second  larger  than  the  elapsed  time. 


Sun  Release  2.0 


Last  change:  2  November  1983 


345 


TIP(IC) 


USER  COMMANDS 


TIP(IC) 


NAME 

tip,  cu  —  connect  to  a  remote  system 
SYNOPSIS 

tip  I  — V  ]  I  —speed  |  system-name 
tip  [  — V  j  I  —speed  j  phone-number 

cu  phone-number  [  — t  [  |  — 8  speed  |  |  —a  acu  [  |  —1  line  ]  (  — #  ] 

DESCRIPTION 

Tip  and  cu  establish  a  fuli-duplex  connection  to  another  machine,  giving  the  appearance  of  being 
logged  in  directly  on  the  remote  computer.  It  goes  without  saying  that  you  must  have  a  account 
on  the  machine  (or  equivalent)  to  which  you  wish  to  connect.  The  preferred  interface  is  tip.  The 
cu  interface  is  included  for  those  people  attached  to  the  ‘call  UNDC  command  of  the  version  7 
UNIX  system.  This  manual  page  describes  only  tip. 

When  lip  starts  up  it  reads  commands  from  the  file  .<»prc  in  your  home  directory.  If  you  use  the 
—V  option  on  the  tip  command  line,  tip  displays  these  commands  as  it  executes  them.  See  the 
discussion  on  variables  later  on. 

Typed  characters  are  normally  transmitted  directly  to  the  remote  machine  (which  does  the  echo¬ 
ing  as  well). 

A  tilde  (‘~’)  appearing  as  the  first  character  of  a  line  is  an  escape  signal  which  directs  tip  to  per¬ 
form  some  special  action.  Tip  recognizes  the  following  escape  sequences: 

Drop  the  connection  and  exit  (you  may  still  be  logged  in  on  the  remote  machine). 

"c  [name] 

Change  directory  to  name  (no  argument  implies  change  to  your  home  directory). 

“!  Escape  to  a  shell  (exiting  the  shell  returns  you  to  tip). 

"’>  Copy  file  from  local  to  remote. 

■'<  Copy  file  from  remote  to  local. 

‘'pfrom  I  to  ] 

Send  a  file  to  a  remote  UNIX  host.  When  you  use  the  put  command,  the  remote  UNIX  sys¬ 
tem  runs  the  command  string 

cat  >  to 

while  tip  sends  it  the  from  file.  If  the  to  file  isn’t  specified,  the  from  file  name  is  used.  This 
command  is  actually  a  UNIX  specific  version  of  the  command. 

"t  from  I  to  ] 

Take  a  file  from  a  remote  UNIX  host.  As  in  the  put  command  the  to  file  defaults  to  the 
from  file  name  if  it  isn’t  specified.  The  remote  host  executes  the  command  string 
eat  >  from;  echo  “A 
to  send  the  file  to  tip. 

"}  Pipe  the  output  from  a  remote  command  to  a  local  UNIX  process.  The  command  string 
sent  to  the  local  UNIX  system  is  processed  by  the  shell. 

"C  Connect  a  program  to  the  remote  machine.  The  command  string  sent  to  the  program  is 
processed  by  the  shell.  The  program  inherits  file  descriptors  0  as  remote  line  input,  1  as 
remote  line  output,  and  2  as  tty  standard  error. 

“#  Send  a  BREAK  to  the  remote  system.  For  systems  which  don’t  support  the  necessary  iocti 
call  the  break  is  simulated  by  a  sequence  of  line  speed  changes  and  DEL  characters. 

Set  a  variable  (see  the  discussion  below). 

“‘Z  Stop  tip  (only  available  when  run  under  the  C-Shell). 
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Get  a  summary  of  the  tilde  escapes 


Copying  files  requires  some  cooperation  on  the  part  of  the  remote  host.  When  a  ">  or 
escape  is  used  to  send  a  file,  tip  prompts  for  a  file  name  (to  be  transmitted  or  received)  and  a 
command  to  be  sent  to  the  remote  system,  in  case  the  file  is  being  transferred  from  the  remote 
system.  The  default  end  of  transmission  string  for  transferring  a  file  from  the  local  system  to  the 
remote  is  specified  as  the  *oe’  parameter  in  the  remote{S)  file,  but  may  be  changed  by  the  set 
command.  While  tip  is  transferring  a  file  the  number  of  lines  transferred  will  be  continuously 
displayed  on  the  screen.  A  file  transfer  may  be  aborted  with  an  interrupt.  An  example  of  the 
dialogue  used  to  transfer  files  is  given  below  (input  typed  by  the  user  is  shown  in  bold  face). 

arpa%  tip  monet 
[connected] 

{assume  we  are  talking  to  another  UNIX  system).,. 
ucbmonet  login:  Bam 
Password: 

monet%  cat  >  Sylvester •€ 

Filename:  Sylvester .c 

32  lines  transferred  in  1  minute  3  seconds 
monet% 

monet%  "'<  Filename:  reply .c 
List  command  for  remote  host;  cat  reply.c 
66  lines  transferred  in  2  minutes 
monet% 

...{or,  equivalently),., 
monet%  ""p  Sylvester .c 

{actually  echoes  as  ^{putj  Sylvester, c), , , 

32  lines  transferred  in  1  minute  3  seconds 
monet% 

monet%  "'t  reply.c 

,  ..{actually  echoes  as  '^[take]  reply, c),., 

65  lines  transferred  in  2  minutes 
monet% 

. .  ,{to  print  a  file  locally), , , 

monet%  '"{Local  command:  pr  -h  Sylvester .c  |  Ipr 
List  command  for  remote  host:  cat  Sylvester 
monet% 

[EOT] 

,,,{back  on  the  local  system),,. 

The  remote{b)  file  contains  the  definitions  for  remote  systems  known  by  tip;  refer  to  the  remote 
manual  page  for  a  full  description.  Each  system  has  a  default  baud  rate  with  which  to  establish 
a  connection.  If  this  value  is  not  suitable,  the  baud  rate  to  be  used  may  be  specified  on  the  com¬ 
mand  line,  for  example: 

tip  —300  mds 

When  tip  establishes  a  connection  it  sends  out  a  connection  message  to  the  remote  system.  The 
default  value  for  this  string  may  be  found  in  the  remote  file. 

At  any  time  that  tip  prompts  for  an  argument  (for  example,  during  setup  of  a  file  transfer)  the 
line  typed  may  be  edited  with  the  standard  erase  and  kill  characters.  A  null  line  in  response  to  a 
prompt,  or  an  interrupt,  aborts  the  dialogue  and  returns  you  to  the  remote  machine. 

When  tip  attempts  to  connect  to  a  remote  system,  it  opens  the  associated  device  with  an 
exclusive-open  ioctl{2)  call.  Thus  only  one  user  at  a  time  may  access  a  device.  This  is  to  prevent 
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multiple  processes  from  sampling  the  terminal  line.  In  addition,  tip  honors  the  locking  protocol 
used  by  uucp(lC), 

AUTO-CALL  UNITS 

Tip  may  be  used  to  dial  up  remote  systems  using  a  number  of  auto-call  unit’s  (ACU’s).  When 
the  remote  system  description  contains  the  Mu’  attribute,  tip  uses  the  call-unit  (‘cu’),  ACU  type 
(‘at’),  and  phone  numbers  (‘pn’)  supplied.  Normally  tip  displays  verbose  messages  as  it  dials.  See 
remot€{b)  for  details  of  the  remote  host  specification. 

Depending  on  the  type  of  auto-dialer  being  used  to  establish  a  connection  the  remote  host  may 
have  garbage  characters  sent  to  it  upon  connection.  The  user  should  never  assume  that  the  first 
characters  typed  to  the  foreign  host  are  the  first  ones  presented  to  it.  The  recommended  prac¬ 
tice  is  to  immediately  type  a  ‘kill’  character  upon  establishing  a  connection  (most  UNIX  systems 
support  as  the  initial  kill  character). 

Tip  currently  supports  the  Ventel  MD-212+  autodialer  modem  and  the  Hayes  SmartModem 

1200, 

REMOTE  HOST  DESCRIPTIONS 

Descriptions  of  remote  hosts  are  normally  located  in  the  system- wide  file  f  etc f remote.  However, 
a  user  may  maintain  personal  description  files  (and  phone  numbers)  by  defining  and  exporting  the 
REMOTE  shell  variable.  The  remote  file  must  be  readable  by  tip,  but  a  secondary  file  describing 
phone  numbers  may  be  maintained  readable  only  by  the  user.  This  secondary  phone  number  file 
is  /etc/phoneSf  unless  the  shell  variable  PHONES  is  defined  and  exported.  As  described  in 
remot€[b)y  the  phones  file  is  read  when  the  host  description’s  phone  number(s)  capability  is  an 
The  phone  number  file  contains  lines  of  the  form: 

system-name  phone-number 

Each  phone  number  found  for  a  system  is  tried  until  either  a  connection  is  established,  or  an  end 
of  file  is  reached.  Phone  numbers  are  constructed  from  *0123456789-=*’,  where  the  ’  and 
are  used  to  indicate  a  second  dial  tone  should  be  waited  for  (ACU  dependent). 

TIP  INTERNAL  VARIABLES 

Tip  maintains  a  set  of  variables  which  are  used  in  normal  operation.  Some  of  these  variables  are 
read-only  to  normal  users  (root  is  allowed  to  change  anything  of  interest).  Variables  may  be 
displayed  and  set  through  the  ‘'"s’  escape.  The  syntax  for  variables  is  patterned  after  w(l)  and 
fna{/(l).  Supplying  ‘all’  as  an  argument  to  the  set  command  displays  all  variables  that  the  user 
can  read.  Alternatively,  the  user  may  request  display  of  a  particular  variable  by  attaching  a 
to  the  end.  For  example  ‘escape?’  displays  the  current  escape  character. 

Variables  are  numeric,  string,  character,  or  Boolean  values.  Boolean  variables  are  set  merely  by 
specifying  their  name.  They  may  be  reset  by  prepending  a  *!’  to  the  name.  Other  variable  types 
are  set  by  appending  an  *  and  the  value.  The  entire  assignment  must  not  have  any  blanks  in 
it.  A  single  set  command  may  be  used  to  interrogate  as  well  as  set  a  number  of  variables. 

Variables  may  be  initialized  at  run  time  by  placing  set  commands  (without  the  ‘"“s’  prefix)  in  a 
Mprc  file  in  one’s  home  directory.  The  —v  option  makes  Up  display  the  sets  as  they  are  made. 
Comments  preceded  by  a  *#’  sign  can  appear  in  the  mtiprc  file. 

Finally,  the  variable  names  must  either  be  completely  specified  or  an  abbreviation  may  be  given. 
The  following  list  details  those  variables  known  to  tip^  their  abbreviations  (surrounded  by  brack¬ 
ets),  and  their  default  values.  Those  variables  initialized  from  the  remote  file  are  marked  with  a 
A  mode  is  given  for  each  variable  —  capitalization  indicates  the  read  or  write  capability  is 
given  only  to  the  super-user. 

Variable  Type  Mode  Default  Description 

[bejautify  bool  rw  true  discard  unprintables  when  scripting 
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(ba|udrate 

num 

rW 

♦ 

connection  baud  rate 

ic]harldelay| 

num 

rw 

0 

character  delay  for  file  transfers  to  remote  (cl) 

idial|timeout 

num 

rW 

60 

timeout  (seconds)  when  establishing  connection 

jdijsconnect 

str 

rw 

string  to  send  to  disconnect  (di) 

[eclhocheck 

bool 

rw 

false 

[eofrjead 

str 

rw 

char’s  signifying  EOT  from  the  remote  host 

[eofw|rite 

str 

rw 

♦ 

string  sent  for  EOT 

[eol] 

str 

rw 

♦ 

end  of  line  indicators 

[es)cape 

char 

rw 

command  prefix  character 

jetjimeout 

num 

rw 

10 

echo  check  timeout  (et) 

|ex|ceptions 

str 

rw 

"\t\n\f\b" 

char’s  not  discarded  due  to  beautification 

jfo[rce 

char 

rw 

f } 

force  character 

|fr|amesize 

num 

rw 

♦ 

size  of  buffering  between  writes  on  reception 

|h|alf[d|uple[x| 

bool 

rw 

falsehost  is  half  duplex  —  do  local  echo  (hd) 

jho|st 

str 

r 

name  of  host  connected  to 

[l]ine|delay| 

num 

rw 

0 

line  delay  for  transfers  to  remote  (dl) 

jljocaI|ejcho 

bool 

rw 

false 

synonym  for  halfduplex 

[lock] 

str 

RW 

**/tmp/aculock" 

lock  file  for  ACU  logging 

[log] 

str 

RW 

"/usr/adm/aculog"ACU  log  file 

[parjity 

str 

rw 

ft  ft 

none 

parity  to  be  generated  (pa) 

[phones] 

str 

r 

V^tc/p  hones" 

file  for  hidden  phone  numbers 

[pr|ompt 

char 

rW 

V’ 

end  of  line  indicator  set  by  host 

[rajise 

bool 

rw 

false 

upper  case  mapping  switch 

[r|aise[c|har 

char 

rw 

fi 

interactive  toggle  for  raise 

[raw  [ftp 

bool 

rw 

false 

send  all  characters  during  file  transfer  (rw) 
do  not  filter  non-printable  characters 
do  not  do  translations  like  \n  to  \r. 

[rec|ord 

str 

rw 

"tip.record" 

name  of  script  output  file 

[remote] 

str 

r 

"/etc/remote" 

system  description  file 

[scjript 

bool 

rw 

false 

session  scripting  switch 

[tabjexpand 

bool 

rw 

false 

expand  tabs  during  file  transfers 

[tajndem 

bool 

rw 

true 

use  XON/XOFF  flow  control  (ta  and  nt) 

[verbjose 

bool 

rw 

true 

make  noise  during  file  transfers 

[SHELL] 

str 

rw 

7bin/sh" 

name  of  shell  for  escape 

[HOME] 

str 

rw 

ftn 

home  directory  for  '"c  escape 

ENVIRONMENT  VARIABLES 

The  following  variables  are  read  from  the  environment: 

REMOTE  The  location  of  the  remote  file. 

PHONES  The  location  of  the  file  containing  private  phone  numbers, 
HOST  A  default  host  to  connect  to. 

HOME  One’s  log-in  directory  (for  chdirs). 

SHELL  The  shell  to  fork  on  a  *'!’  escape. 

FILES 

"/.tiprc  initialization  file. 

/usr/spool/uucp/LCK..*  lock  file  to  avoid  conflicts  with  nucp 

DIAGNOSTICS 

Diagnostics  are,  hopefully,  self  explanatory. 
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SEE  ALSO 

remote(5),  phones(5) 

BUGS 

Note  that  chardelay  and  linedelay  are  currently  not  implemented. 
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NAME 

touch  —  update  date  last  modified  of  a  file 
SYNOPSIS 

touch  [  — c  I  I  — f  I  file  ♦ . . 

DESCRIPTION 

Toxich  attempts  to  set  the  modified  date  of  each  file.  If  the  file  exists,  this  is  done  by  reading  a 
character  from  the  file  and  writing  it  back. 

Touch  is  valuable  when  used  in  conjunction  with  maite(l),  where,  for  instance,  you  might  want  to 
force  a  complete  rebuild  of  a  program  composed  of  many  pieces.  In  such  a  case,  you  might  type, 
for  example: 

%  touch  ♦.c 
%  m&ke 

and  the  make  would  then  see  that  all  the  *0  files  were  more  up  to  date  than  all  the  corresponding 
•o  files,  and  would  start  the  build  from  scratch. 

OPTIONS 

— c  Do  not  attempt  to  create  a  file  if  it  does  not  exist. 

—t  Attempt  to  force  the  touch  in  spite  of  read  and  write  permissions  on  a  file. 

SEE  ALSO 

utimes(2) 
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NAME 

tr  —  translate  characters 
SYNOPSIS 

tr  [  —cdi  I  [  stringl  [  string2  ]  ] 

DESCRIPTION 

Tr  copies  the  standard  input  to  the  standard  output  with  substitution  or  deletion  of  selected 
characters.  The  arguments  stringl  and  stringS  are  considered  sets  of  characters.  Input  charac¬ 
ters  found  in  stringl  are  mapped  into  the  corresponding  characters  of  stringS.  When  stringS  is 
short  it  is  padded  to  the  length  of  stringl  by  duplicating  its  last  character. 

In  either  string  the  notation  a—b  means  a  range  of  characters  from  u  to  i  in  increasing  ASCII 
order.  The  character  \  followed  by  1,  2  or  3  octal  digits  stands  for  the  character  whose  ASCII 
code  is  given  by  those  digits.  A  \  followed  by  any  other  character  stands  for  that  character. 

OPTIONS 

Any  combination  of  the  options  — eda  may  be  used: 

— c  Complement  the  set  of  characters  in  stringl  with  respect  to  the  universe  of  characters 

whose  ASCII  codes  are  01  through  0377  octal; 

— d  Delete  all  input  characters  in  stringl; 

s  Squeeze  all  strings  of  repeated  output  characters  that  are  in  stringS  to  single  characters. 
EXAMPLE 

The  following  example  creates  a  list  of  all  the  words  in  ‘filel’  one  per  line  in  *file2*,  where  a  word 
is  taken  to  be  a  maximal  string  of  alphabetics.  The  second  string  is  quoted  to  protect  *\  from 
the  Shell.  012  is  the  ASCII  code  for  newline. 

tr  — cs  A— Za— z  ‘'\012'  <filel  >file2 

SEE  ALSO 

ed(l),  ascii(7),  expand(l) 

BUGS 

Won’t  handle  ASCII  NUL  in  stringl  or  stringS;  always  deletes  NUL  from  input. 
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NAME 

trotf  —  typeset  or  format  documents 
SYNOPSIS 

troff  I  — o pagelist  ]  (  ~nN  \  [  —*N  |  [  — m  name  |  |  — kjN  |  [  — 1 1  [  — q  j  |  — 1 1  [  — f  ] 

I  -w  j  [  -b  I  [  -a  ]  [  -pN  j  [  file  ) ... 

DESCRIPTION 

Troff  formats  text  in  the  named  files.  The  output  is  by  default  destined  for  printing  on  a 
Graphic  Systems  C/A/T  phototypesetter,  but  suitable  postprocessing  software  can  convert  the 
C/A/T  output  to  a  form  which  can  be  directed  to  other  high-resolution  devices.  See  also  the 
nro^(l)  manual  page,  which  describes  a  formatter  which  formats  text  for  typewriter-like  devices. 
The  capabilities  of  both  troff  and  nroff  are  described  in  Formatting  Documents  with  Nroff  and 
Troff, 

If  no  file  argument  is  present,  the  standard  input  is  read.  An  argument  consisting  of  a  single 
minus  (—)  is  taken  to  be  a  file  name  corresponding  to  the  standard  input. 

OPTIONS 

Options  may  appear  in  any  order  so  long  as  they  appear  before  the  files, 

—olist  Print  only  pages  whose  page  numbers  appear  in  the  comma-separated  list  of  numbers 
and  ranges.  A  range  N--M  means  pages  N  through  M;  an  initial  — iV  means  from  the 
beginning  to  page  N;  and  a  final  N—  means  from  iVto  the  end. 

—nN  Number  first  generated  page  N, 

—mname 

Prepend  the  macro  file  /uBr/llb/tmae/tmac.nume  to  the  input  files, 

--raN  Set  register  a  (one-character)  to  N, 

“^1  Read  standard  input  after  the  input  files  are  exhausted. 

— q  Invoke  the  simultaneous  input-output  mode  of  the  rd  request. 

— t  Direct  output  to  the  standard  output  instead  of  the  phototypesetter.  In  general,  you  will 

have  to  use  this  option  if  you  don’t  have  a  typesetter  attached  to  the  system. 

—a  Send  a  printable  ASCII  approximation  of  the  results  to  the  standard  output. 

Some  options  of  troff  only  apply  if  you  have  a  C/A/T  typesetter  attached  to  your  system.  These 
options  are  here  for  historical  reasons: 

—sN  Stop  every  N  pages.  Troff  stops  the  phototypesetter  every  N  pages,  produces  a  trailer  to 
allow  changing  cassettes,  and  resumes  when  the  typesetter’s  start  button  is  pressed. 

— f  Refrain  from  feeding  out  paper  and  stopping  phototypesetter  at  the  end  of  the  run. 

—w  Wait  until  phototypesetter  is  available,  if  currently  busy. 

*-b  Report  whether  the  phototypesetter  is  busy  or  available.  No  text  processing  is  done. 

— pN  Print  all  characters  in  point  size  N  while  retaining  all  prescribed  spacings  and  motions, 
to  reduce  phototypesetter  elasped  time. 

If  the  file  /uer/adm/tracct  is  writable,  troff  keeps  phototypesetter  accounting  records  there.  The 
integrity  of  that  file  may  be  secured  by  making  troff  a  ’set  user-id’  program. 

FILES 

/tmp/ta*  temporary  file 

/usr/lib/tmac/tmac.*  standard  macro  files 
/usr/lib/term/*  terminal  driving  tables  for  nroff 

/usr /lib/font/*  font  width  tables  for  troff 

/dev/cat  p  hototy  pesetter 
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/usr/adm/tracct  accounting  statistics  for  /dev /cat 
SEE  ALSO 

Formatting  Documents  with  Nroff  and  Troff  in 
Editing  and  Text  Processing  on  the  Sun  Workstation 
nroff(l),  eqn(l),  tbl(l),  ms(7),  me(7),  man(7),  col(l),  checknr(l) 
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NAME 

true,  false  —  provide  truth  values 

SYNOPSIS 

true 

false 

DESCRIPTION 

True  and  false  are  usually  used  in  a  Bourne  shell  script.  They  test  for  the  appropriate  status 
’’true”  or  ^’false’*  before  running  (or  failing  to  run)  a  list  of  commands. 

EXAMPLE 


while  true 
do 

command  list 
done 

SEE  ALSO 

csh(l),  sh(l),  false(l) 

DIAGNOSTICS 

True  has  exit  status  zero. 
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NAME 

tset  —  establish  terminal  characteristics  for  the  environment 
SYNOPSIS 

tset  [  -  )  1  -ec  ]  [  -1 1  I  -kc  ]  |  -n  |  [  -Q  t  I  — '  I  [  -■  1  i  “S  | 

[  — m  \port-ID[baudrate\\:type\  ...  ]  |  type  j 

reset 

DESCRIPTION 

Tsei  sets  up  your  terminal,  typically  when  you  first  log  in.  It  does  terminal  dependent  process¬ 
ing  such  as  setting  erase  and  kill  characters,  setting  or  resetting  delays,  sending  any  sequences 
needed  to  properly  initialized  the  terminal,  and  the  like.  Tset  first  determines  the  type  of  termi¬ 
nal  involved,  and  then  does  necessary  initializations  and  mode  settings.  The  type  of  terminal 
attached  to  each  UNIX  port  is  specified  in  the  letc/ttytype  database.  Type  names  for  terminals 
may  be  found  in  the  ter7ncap{5)  database.  If  a  port  is  not  wired  permanently  to  a  specific  termi¬ 
nal  (not  hardwired)  it  is  given  an  appropriate  generic  identifier  such  as  dialup. 

Reset  turns  off  cbreak  and  raw  modes,  output  delays,  and  parity  checking;  turns  on  newline 
translation,  echo,  and  tab  expansion;  and  restores  undefined  special  characters  to  their  default 
state.  Then  it  sets  the  modes  as  usual,  based  on  the  terminal  type  (which  will  probably  override 
some  of  the  above).  (See  for  more  information.)  Reset  also  uses  the  and  r/=*  ’’reset 

string  and  file"  instead  of  the  initialization  string  and  file  from  / etc/termcap .  This  is  useful  after 
a  program  dies  and  leaves  the  terminal  in  a  funny  state.  Often  in  this  situation,  characters  will 
not  echo  as  you  type  them.  You  may  have  to  type  “<LF>reset<LF>*’  since  <CR>  may  not  work. 


When  no  arguments  are  specified,  tset  simply  reads  the  terminal  type  out  of  the  TERM  environ¬ 
ment  variable  and  re-initializes  the  terminal.  Tset  also  performs  mode  and  environment  initializa¬ 
tion  —  typically  done  once  at  login  —  and  options  used  at  initialization  time  to  determine  the 
terminal  type  and  set  up  terminal  modes. 

When  used  in  a  startup  script  {.profile  for  M(l)  users  or  Jogin  for  csh{l)  users)  it  is  desirable  to 
give  information  about  the  type  of  terminal  you  will  usually  use  on  ports  that  are  not  hardwired. 
These  ports  are  identified  in  /etc/ttytype  as  dialup  or  plugboard,  etc.  Any  of  the  alternate  gen¬ 
eric  names  given  in  termcap  may  be  used  for  the  identifier.  Refer  to  the  — m  option  under 
OPTIONS  for  more  information.  If  no  mapping  applies  and  a  final  type  option,  not  preceded  by  a 
— m,  is  given  on  the  command  line  then  that  type  is  used;  otherwise  the  identifier  found  in  the 
/etcittytype  database  is  used  as  the  terminal  type.  This  should  always  be  the  case  for  hardwired 
ports. 

It  is  usually  desirable  to  return  the  terminal  type,  as  finally  determined  by  tset,  and  information 
about  the  terminal's  capabilities  to  a  shell’s  environment.  This  can  be  done  using  the  — ,  -b,  or  -S 
options.  Refer  to  OPTIONS  for  more  information.  8h{l): 

export  TERM;  TERM=Hset  —  options,,.^ 
or  using  the  C  shell,  csh{l): 

setenv  TERM  ’'tset  —  options,,.^ 

With  csh  it  is  convenient  to  make  an  alias  in  your  .cshrc: 

alias  tset  ^setenv  TERM  "tset  —  \!*"  ^ 

Either  of  these  aliases  allow  the  command 
tset  2621 

to  be  invoked  at  any  time  from  your  login  csh.  Note  to  Bourne  Shell  users:  It  is  not  possible 
to  get  this  aliasing  effect  with  a  shell  script,  because  shell  scripts  cannot  set  the  environment  of 
their  parent.  If  a  process  could  set  its  parent’s  environment,  none  of  this  nonsense  would  be 
necessary  in  the  first  place. 
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Once  the  terminal  type  is  known,  tset  engages  in  terminal  driver  mode  setting.  This  normally 
involves  sending  an  initialization  sequence  to  the  terminal,  setting  the  single  character  erase  (and 
optionally  the  line-kill  (full  line  erase))  characters,  and  setting  special  character  delays.  Tab  and 
newline  expansion  are  turned  off  during  transmission  of  the  terminal  initialization  sequence. 

On  terminals  that  can  backspace  but  not  overstrike  (such  as  a  CRT),  and  when  the  erase  charac¬ 
ter  is  the  erase  character  Is  changed  as  if  -e  had  been  used. 

OPTIONS 

—  The  name  of  the  terminal  finally  decided  upon  is  output  on  the  standard  output.  This  is 
intended  to  be  captured  by  the  shell  and  placed  in  the  TERM  environment  variable. 

— ec  Set  the  erase  character  to  be  the  named  character  c  on  all  terminals.  Default  is  the 

backspace  key  on  the  keyboard,  usually  "H.  The  character  c  can  cither  be  typed 
directly,  or  entered  using  the  hat  notation  used  here. 

—I  Suppress  transmitting  terminal-initialization  strings. 

— kc  Set  the  line  kill  character  to  be  the  named  character  c  on  all  terminals.  Default  is  "U. 

The  kill  character  is  left  alone  if  — k  is  not  specified.  The  hat  notation  can  also  be  used 

for  this  option, 

— n  Specifies  that  the  new  tty  driver  modes  should  be  initialized  for  this  terminal.  Probably 

useless  since  stty  new  is  the  default. 

—Q  Suppress  printing  the  “Erase  set  to”  and  “Kill  set  to”  messages. 

— r  In  addition  to  other  actions,  reports  the  terminal  type. 

— B  Output  eetenv  commands  for  TERM  and  TERMCAP.  This  can  be  used  with 

set  noglob 
eval  Hset  — s  ...^ 
unset  noglob 

and  is  preferred  to  'setenv  TERM  'tset  —  ,  . 
up  much  faster. 

— S  Similar  to  the  —s  option,  but  outputs  two 

follows: 

set  noglob 

set  t— ('‘tset  — S  . ..') 
setenv  TERM  $t[l] 
setenv  TERMCAP  ’*$t[2)" 
unset  t 
unset  noglob 

— m  \port-ID[baudrate\:type\  ... 

Specify  (**map'*)  a  terminal  type  when  connected  to  a  generic  port  (such  as  dialup  or  plug¬ 
board)  identified  by  port-ID,  The  baudrate  argument  (see  also,  ^^^i/(l))  can  be  used  to 
check  the  baudrate  of  the  port  and  set  the  terminal  type  accordingly.  The  target  rate  is 
prefixed  by  any  combination  of  the  following  operators: 

>  is  greater  than 

@  equals  or  ”at" 

<  is  less  than 

I  it  is  not  the  case  that  (negates  the  above  operators) 

to  specify  the  conditions  under  which  the  mapping  is  made. 

In  the  following  example,  the  terminal  type  is  set  to  admSa  if  the  port  is  a  dialup  with  a  speed  of 
greater  than  300  or  to  dw^  if  the  port  is  a  dialup  at  300  baud  or  less.  In  the  third  case,  the  ques¬ 
tion  mark  preceeding  the  terminal  type  indicates  that  the  user  is  to  verify  the  type  desired.  A 


because  it  makes  programs  such  as  ri(l)  start 
strings  suitable  for  use  in  csA(l)  Jogin  files  as 
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null  response  indicates  that  the  named  type  is  correct.  Otherwise,  the  user’s  response  is  taken  to 
be  the  type  desired. 

tset  — m  ’dialup>300;adm3a’  — m  ’dialup:dw2’  — m  ’plugboard:?adm3a’ 

To  prevent  interpratation  as  metacharacters,  the  entire  argument  to  — m  should  be  enclosed  in 
single  quotes.  When  using  the  C-shell,  exclamation  points  should  be  preceded  by  a  backslash  (\). 

EXAMPLES 

These  examples  all  assume  the  C-shell  and  use  the  -s  option.  If  you  use  the  Bourne  shell,  use 
one  of  the  variations  described  above.  Note  that  a  typical  use  of  tset  in  a  .profile  or  .login  will 
also  use  the  — e  and  — k  options,  and  often  the  — n  or  — Q  options  as  well.  These  options  have 
not  been  included  here  to  keep  the  examples  small. 

At  the  moment,  you  are  on  a  2621.  This  is  suitable  for  typing  by  hand  but  not  for  a  .profile, 
unless  you  are  always  on  a  2621. 

set  noglob;  eval  'tset  -s  2621';  unset  noglob 

You  have  an  hl9  at  home  which  you  dial  up  on,  but  your  office  terminal  is  hardwired  and  known 
in  /etc/tty type. 

set  noglob;  eval  'tset  — s  — m  dialup:hl9';  unset  noglob 

You  have  a  switch  which  connects  everything  to  everything,  making  it  nearly  impossible  to  key 
on  what  port  you  are  coming  in  on.  You  use  a  vtlOO  in  your  office  at  9600  baud,  and  dial  up  to 
switch  ports  at  1200  baud  from  home  on  a  2621.  Sometimes  you  use  someone  else’s  terminal  at 
work,  so  you  want  it  to  ask  you  to  make  sure  what  terminal  type  you  have  at  high  speeds,  but  at 
1200  baud  you  are  always  on  a  2621.  Note  the  placement  of  the  question  mark,  and  the  quotes 
to  protect  the  greater  than  and  question  mark  from  interpretation  by  the  shell. 

set  noglob;  eval  'tset  — s  — m  ’switch>1200:?vtl00’  -m  ’swltch<=1200:2621’';  unset 
noglob 

All  of  the  above  entries  will  fall  back  on  the  terminal  type  specified  in  jetclttytype  if  none  of  the 
conditions  hold.  The  following  entry  is  appropriate  if  you  always  dial  up,  always  at  the  same 
baud  rate,  on  many  different  kinds  of  terminals.  Your  most  common  terminal  is  an  admSa.  It 
always  asks  you  what  kind  of  terminal  you  are  on,  defaulting  to  adm3a. 

set  noglob;  eval  'tset  — s  ?adm3a';  unset  noglob 

If  the  file  letcfttytype  is  not  properly  installed  and  you  want  to  key  entirely  on  the  baud  rate,  the 
following  can  be  used; 

set  noglob;  eval  'tset  -s  -m  ’>1200:vtl00’  2621';  unset  noglob 

Here  is  a  fancy  example  to  illustrate  the  power  of  tset  and  to  hopelessly  confuse  anyone  who  has 
made  it  this  far.  You  dial  up  at  1200  baud  or  less  on  a  conceptlOO,  sometimes  over  switch  ports 
and  sometimes  over  regular  dialups.  You  use  various  terminals  at  speeds  higher  than  1200  over 
switch  ports,  most  often  the  terminal  in  your  office,  which  is  a  vtlOO.  However,  sometimes  you 
log  in  from  the  university  you  used  to  go  to,  over  the  ARPANET;  in  this  case  you  are  on  an 
ALTO  emulating  a  dm2600.  You  also  often  log  in  on  various  hardwire'd  ports,  such  as  the  con¬ 
sole,  all  of  which  are  properly  entered  in  /etcjttytype.  You  want  your  erase  character  set  to  con¬ 
trol  H,  your  kill  character  set  to  control  U,  and  don’t  want  tset  to  print  the  “Erase  set  to  Back¬ 
space,  Kill  set  to  Control  U”  message.  This  example  appears  to  take  up  more  than  one  line. 
When  you  type  in  real  tset  commands,  you  must  enter  them  entirely  on  one  line. 

set  noglob;  eval  'tset  -e  -k'U  -Q  -s  -m  ’switch<=1200:conceptl00’  -m 
’switch:?vtl00’  — m  dialup:conceptl00  — m  arpanet:dm2500';  unset  noglob 

FILES 

/etc/ttytype  port  name  to  terminal  type  mapping  database 

/etc/termcap  terminal  capability  database 
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/usr/lib/tabset/*  tab  setting  sequences  for  various  terminals.  Pointed  to  by  termcap 
entries. 

SEE  ALSO 

C5h(l),  sh(l),  stty(l),  ttytype(5),  termcap(5),  environ(5) 

BUGS 

The  tset  command  is  one  of  the  first  commands  a  user  must  master  when  getting  started  on  a 
UNDC  system.  Unfortunately,  it  is  one  of  the  most  complex,  largely  because  of  the  extra  effort 
the  user  must  go  through  to  get  the  environment  of  the  login  shell  set.  Something  needs  to  be 
done  to  make  all  this  simpler,  either  the  foirtn(l)  program  should  do  this  stuff,  or  a  default  shell 
alias  should  be  made,  or  a  way  to  set  the  environment  of  the  parent  should  exist. 

It  could  well  be  argued  that  the  shell  should  be  responsible  for  ensuring  that  the  terminal 
remains  in  a  sane  state;  this  would  eliminate  the  need  for  the  reset  program. 
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NAME 

tsort  —  topological  sort 


SYNOPSIS 

tsort  I  file  ] 


DESCRIPTION  .  .  .  .  .  .  , 

Tsort  produces  on  the  standard  output  a  totally  ordered  list  of  items  consistent  with  a  partial 

ordering  of  items  mentioned  in  the  input  file.  If  no  file  is  specified,  the  standard  input  is  under- 
stood. 

The  input  consists  of  pairs  of  items  (nonempty  strings)  separated  by  blanks.  Pairs  of  different 
items  indicate  ordering.  Pairs  of  identical  items  indicate  presence,  but  not  ordering. 


SEE  ALSO 

lorder(l) 

BUGS 

Uses  a  quadratic  algorithm;  not  worth  fixing  for  the  typical  use  of  ordering  a  library  archive  file. 
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TTY(l) 


NAME 

tty  —  get  terminal  name 

SYNOPSIS 

tty  (  -■  j 

DESCRIPTION 

Tty  prints  the  pathname  of  the  user’s  terminal  unless  the  — «  (silent)  option  is  given.  In  either 
case,  the  exit  value  is  zero  if  the  standard  input  is  a  terminal,  and  one  if  it  is  not. 
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USER  COMMANDS 


UL(1) 


NAME 

u!  —  do  underlining 
SYNOPSIS 

ul  I  — I  ]  [  — t  terminal  |  [  file  ...  ] 

DESCRIPTION 

Ul  reads  the  named  files  (or  standard  input  if  none  arc  given)  and  translates  occurrences  of 
underscores  to  the  sequence  which  indicates  underlining  for  the  terminal  in  use,  as  specified  by 
the  environment  variable  TERM,  ul  uses  the  fetc/termcap  file  to  determine  the  appropriate 
sequences  for  underlining.  If  the  terminal  is  incapable  of  underlining,  but  is  capable  of  a  standout 
mode  then  that  is  used  instead.  If  the  terminal  can  overstrike,  or  handles  underlining  automati¬ 
cally,  ul  degenerates  to  caf(l).  If  the  terminal  cannot  underline,  underlining  is  ignored. 

OPTIONS 

— t  Override  the  terminal  kind  specified  in  the  environment.  If  the  terminal  cannot  under¬ 

line,  underlining  is  ignored. 

— i  Indicate  underlining  onto  by  a  separate  line  containing  appropriate  dashes  this  is  use¬ 

ful  when  you  want  to  look  at  the  underlining  which  is  present  in  an  nroff  output  stream 
on  a  crt-terminal. 

SEE  ALSO 

man(l),  nroff(l),  colcrt(l) 

BUGS 

Nroff  usually  generates  a  series  of  backspaces  and  underlines  intermixed  with  the  text  to  indicate 
underlining.  Ul  makes  attempt  to  optimize  the  backward  motion. 
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UNGET(l) 


NAME 

unget  --  undo  a  previous  get  of  an  SCCS  file 
SYNOPSIS 

/usr/Bccs/unget  [  — rS/Z)  |  [  — s  |  |  — n  |  file 
DESCRIPTION 

Unget  undoes  the  effect  of  a  get  — e  done  prior  to  creating  the  intended  new  delta.  If  a  direc¬ 
tory  is  named,  unget  behaves  as  though  each  file  in  the  directory  were  specified  as  a  named  file, 
except  that  non-SCCS  files  and  unreadable  files  are  silently  ignored.  If  a  name  of  —  is  given,  the 
standard  input  is  read  with  each  line  being  taken  as  the  name  of  an  SCCS  file  to  be  processed. 

OPTIONS 

Options  apply  independently  to  each  named  file. 

—tSID  Uniquely  identifies  which  delta  is  no  longer  intended.  (This  would  have  been  specified  by 
get  as  the  “new  delta^’).  The  — r  option  is  necessary  only  if  two  or  more  outstanding 
gets  for  editing  on  the  same  SCCS  file  were  done  by  the  same  person  (login  name).  A 
diagnostic  results  if  the  specified  S/D  is  ambiguous,  or  if  it  is  necessary  but  omitted  from 
the  command  line. 

—8  Suppress  displaying  the  intended  delta’s  SID, 

— n  Retain  the  gotten  file  —  it  is  normally  removed  from  the  current  directory. 

SEE  ALSO 

sccs(l),  delta(l),  get(l),  sact(l). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 

DIAGNOSTICS 

Use  kelp[\)  for  explanations. 
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NAME 

uniq  —  report  repeated  lines  in  a  file 
SYNOPSIS 

uniq  I  -udc  1  +n  ]  [  -n  ]  ]  1  input  [  output  ]  j 
DESCRIPTION 

Uniq  reads  the  input  file  comparing  adjacent  lines.  In  the  normal  case,  the  second  and  succeed¬ 
ing  copies  of  repeated  lines  are  removed;  the  remainder  is  written  on  the  output  file.  Note  that 
repeated  lines  must  be  adjacent  in  order  to  be  found;  see  aorf(l). 

OPTIONS 

— u  Copy  only  those  lines  which  are  not  repeated  in  the  original  file. 

— d  Write  one  copy  of  just  the  repeated  lines. 

The  normal  output  of  uniq  is  the  union  of  the  — u  and  — d  options 

_ ^  supersedes  — u  and  — d  and  generates  an  output  report  in  default  style  but  with  each  line 

preceded  by  a  count  of  the  number  of  times  it  occurred. 

The  n  arguments  specify  skipping  an  initial  portion  of  each  line  in  the  comparison: 

-n  The  first  n  fields  together  with  any  blanks  before  each  are  ignored.  A  field  is  defined  as 
a  string  of  non-space,  non-tab  characters  separated  by  tabs  and  spaces  from  its  neigh¬ 
bors. 

+n  The  first  n  characters  are  ignored.  Fields  are  skipped  before  characters. 

SEE  ALSO 

sort(l),  comm(l) 
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NAME 

units  —  conversion  program 

SYNOPSIS 

units 

DESCRIPTION 

Units  converts  quantities  expressed  in  various  standard  scales  to  their  equivalents  in  other  scales. 
It  works  interactively  in  this  fashion: 

You  have:  inch 
You  want:  cm 

♦  2.54000e^00 
f  S.9S701e-01 

A  quantity  is  specified  as  a  multiplicative  combination  of  units  optionally  preceded  by  a  numeric 
multiplier.  Powers  are  indicated  by  suffixed  positive  integers,  division  by  the  usual  sign: 

You  have:  15  pounds  force/in2 
You  want:  atm 

*  L02069e+00 
/  9,797S0e-01 

Units  only  does  multiplicative  scale  changes.  Thus  it  can  convert  Kelvin  to  Rankine,  but  not 
Centigrade  to  Fahrenheit.  Most  familiar  units,  abbreviations,  and  metric  prefixes  are  recognized, 
together  with  a  generous  leavening  of  exotica  and  a  few  constants  of  nature  including: 


pi 

ratio  of  circumference  to  diameter 

c 

speed  of  light 

e 

charge  on  an  electron 

g 

acceleration  of  gravity 

force 

same  as  g 

mole 

Avogadro’s  number 

water 

pressure  head  per  unit  height  of  water 

au 

astronomical  unit 

‘Pound’  is  a  unit  of  mass.  Compound  names  are  run  together,  e.g.  ‘lightyear’.  British  units  that 
differ  from  their  US  counterparts  are  prefixed  thus:  ‘brgallon’.  Currency  is  denoted  ‘belgium- 
franc’,  ‘britainpound’,  ... 

For  a  complete  list  of  units,  ‘cat  /usr/Iib/units*. 

FILES 

/usr/lib/units 

BUGS 

Don’t  base  your  financial  plans  on  the  currency  conversions. 
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NAME 

uptime  —  show  how  long  system  has  been  up 

SYNOPSIS 

uptime 

DESCRIPTION 

Uptime  prints  the  current  time,  the  length  of  time  the  system  has  been  up,  and  the  average 
number  of  jobs  in  the  run  queue  over  the  last  1,  5  and  15  minutes.  It  is,  essentially,  the  first  line 
of  a  u)(l)  command. 

EXAMPLE 

angel%  uptime 

6;47am  up  6  days,  16:38,  1  users,  load  average:  0.69,  0.28,  0.17 
angel% 

FILES 

/vmunix  system  name  list 

SEE  ALSO 
w(l) 
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NAME 

users  —  compact  list  of  users  who  are  on  the  system 

SYNOPSIS 

users 

DESCRIPTION 

Users  lists  the  login  names  of  the  users  currently  on  the  system  in  a  compact,  one-line  format: 

%  users 

john  paul  george 

% 

FILES 

/etc/utmp 

SEE  ALSO 

who(l) 
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NAME 

UUCP,  uulog  —  Unix  to  unix  copy 
SYNOPSIS 

UUCP  [  _c  I  (  — c  I  I  — d  ]  1  — m  )  source^le  ...  it8tination_filt 
uulog  I  —teya  j  [  — u««er  | 

DESCRIPTION 

Uucp  copies  files  named  by  the  source-file  arguments  to  the  destination-file  argument.  A  file 
name  may  be  a  path  name  on  your  machine,  or  may  have  the  form 

system-namelpathname 

where  ‘system-name’  Is  taken  from  a  list  of  system  names  which  uucp  knows  about.  Shell  meta¬ 
characters  ?  *  [  ]  appearing  in  the  pathname  part  will  be  expanded  on  the  appropriate  system. 

Pathnames  may  be  one  of 

a  full  pathname; 

a  pathname  preceded  by  ‘user;  where  user  is  a  userid  on  the  specified  system  and  is 
replaced  by  that  user’s  login  directory; 

anything  else  is  prefixed  by  the  current  directory. 

result  is  an  erroneous  pathname  for  the  remote  system  the  copy  will  fail.  If  the 
destination-file  is  a  directory,  the  last  part  of  the  source-file  name  is  used. 

Uucp  preserves  execute  permissions  across  the  transmission  and  gives  0666  read  and  write  per¬ 
missions  (see  chmod{2)). 

Uulog  maintains  a  summary  log  of  uucp  and  tiaa;(lC)  transactions  in  the  file 
I usrf  spool/ uucp/ LOGFILE,  by  gathering  information  from  partial  log  files  named 
/u$r/ spool/ uucp/ LOG.*.?.  It  removes  the  partial  log  files. 

OPTIONS 

The  following  options  are  interpreted  by  uucp. 

— C  Make  a  copy  of  outgoing  files  in  the  uucp  spool  directory,  rather  than  copying  the  source 
file  directly  to  the  target  system.  This  lets  you  remove  the  source  file  after  issuing  the 
uucp  command. 

— c  Use  the  source  file  when  copying  out  rather  than  copying  the  file  to  the  spool  directory. 
This  is  the  default. 

— d  Make  all  necessary  directories  for  the  file  copy. 

— m  Send  mail  to  the  requester  when  the  copy  is  complete. 

UULOG  OPTIONS 

—Bsys  Print  information  about  work  involving  system  sys. 

— uuaer 

Print  information  about  work  done  for  the  specified  user. 

FILES 

/usr/spool/uucp  spool  directory 

/usr/lib/uucp/*  other  data  and  program  files 

SEE  ALSO 

uux(lC),  mail(l) 

Uucp  Implementation  Description  in  the  Sun  System  Manager’s  Manual. 

WARNING 


(1) 

(2) 

(3) 

If  the 
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The  domain  of  remotely  accessible  files  can  (and  for  obvious  security  reasons,  usualiy  should)  be 
severely  restricted.  You  will  very  likely  not  be  able  to  fetch  files  by  pathname;  ask  a  responsible 
person  on  the  remote  system  to  send  them  to  you.  For  the  same  reasons  you  will  probably  not 
be  able  to  send  files  to  arbitrary  pathnames. 

BUGS 

All  files  received  by  uucp  will  be  owned  by  uucp. 

The  — m  option  will  only  work  sending  files  or  receiving  a  single  file.  Receiving  multiple  files 
specified  by  special  shell  characters  ?  ♦  [  ]  will  not  activate  the  — m  option. 
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NAME 

uucncode,uudecod6  —  encode/decode  &  binary  file  for  transmission  via  mail 
SYNOPSIS 

uuencode  |  source-file  ]  destination-file  j  midl  5ysl!sys2!...!decode 
uudecode  |  source-file  | 

DESCRIPTION 

Uuencode  and  uudecode  are  used  to  send  a  binary  file  via  uucp  (or  other)  mail.  This  combina¬ 
tion  of  commands  can  be  used  over  indirect  mail  links  even  when  uttsenrf(lC)  is  not  available. 

Uuencode  takes  the  named  source  file  (default  standard  input)  and  produces  an  encoded  version 
on  the  standard  output.  The  encoding  uses  only  printing  ASCII  characters,  and  includes  the 
mode  of  the  file  and  the  remotedest  for  recreation  on  the  remote  system. 

Uudecode  reads  an  encoded  file,  strips  off  any  leading  and  trailing  lines  added  by  mailers,  and 
recreates  the  original  file  with  the  specified  mode  and  name. 

The  intent  is  that  all  mail  to  the  user  “decode”  should  be  filtered  through  the  uudecode  pro¬ 
gram.  This  way  the  file  is  created  automatically  without  human  intervention.  This  is  possible  on 
the  uucp  network  by  either  using  sendmail  or  by  making  rma:V  be  a  link  to  Mail  instead  of  mail. 
In  each  case,  an  alias  must  be  created  in  a  master  file  to  get  the  automatic  invocation  of 
uudecode. 

If  these  facilities  are  not  available,  the  file  can  be  sent  to  a  user  on  the  remote  machine  who  can 
uudecode  it  manually. 

The  encode  file  has  an  ordinary  text  form  and  can  be  edited  by  any  text  editor  to  change  the 
mode  or  remote  name. 

SEE  ALSO 

uuencode(5),  uusend(lC),  uucp(IC),  uux(IC),  mail(I) 

BUGS 

The  file  is  expanded  by  35%  (3  bytes  become  4  plus  control  information)  causing  it  to  take  longer 
to  transmit. 

The  user  on  the  remote  system  who  is  invoking  uudecode  (often  uucp)  must  have  write  permis¬ 
sion  on  the  specified  file. 
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NAME 

uusend  —  send  a  file  to  a  remote  host 
SYNOPSIS 

uusend  [  -“in  mode  |  sourcefile  sysl!sys2!,.!remotefile 
DESCRIPTION 

Uusend  sends  a  file  to  a  given  location  on  a  remote  system.  The  system  need  not  be  directly  con¬ 
nected  to  the  local  system,  but  a  chain  of  ««cp(lC)  links  needs  to  connect  the  two  systems. 

The  sourcefile  can  be  meaning  to  use  the  standard  input.  Both  of  these  options  are  pri¬ 

marily  intended  for  internal  use  of  uusend. 

The  remotefile  can  include  the  "userid  syntax. 

OPTIONS 

— m  mode 

Take  the  mode  of  the  file  on  the  remote  end  from  the  octal  number  specified  as  mode. 
The  mode  of  the  input  file  is  used  if  the  — m  option  is  not  specified. 

DIAGNOSTICS 

If  anything  goes  wrong  any  further  away  than  the  first  system  down  the  line,  you  will  never  hear 
about  it. 

SEE  ALSO 

uux(lC),  uucp(lC),  uuencode(lC) 

BUGS 

This  command  shouldn’t  exist,  since  uucp  should  handle  it. 

All  systems  along  the  line  must  have  the  uusend  command  available  and  allow  remote  execution 
of  it. 

Some  UUCP  systems  have  a  bug  where  binary  files  cannot  be  the  input  to  a  uux  command.  If 
this  bug  exists  in  any  system  along  the  line,  the  file  will  show  up  severely  munged. 
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NAME 

uux  —  Unix  to  Unix  command  execution 
SYNOPSIS 

uux  [  —  )  I  — r  ]  [  — xn  ]  (  — 1  ]  I  — gj  |  command-string 
DESCRIPTION 

Uux  will  gather  0  or  more  files  from  various  systems,  execute  a  command  on  a  specified  system 
and  send  standard  output  to  a  file  on  a  specified  system. 

The  command-string  is  made  up  of  one  or  more  arguments  that  look  like  a  shell  command  line, 
except  that  the  command  and  file  names  may  be  prefixed  by  system-name!,  A  null  system-name 
is  interpreted  as  the  local  system. 

File  names  may  be  one  of 

(1)  a  full  pathname; 

(2)  a  pathname  preceded  by  ^xxx;  where  xxx  is  a  userid  on  the  specified  system  and  is 
replaced  by  that  user’s  login  directory; 

(3)  anything  else  is  prefixed  by  the  current  directory, 

Xhe  ’  option  will  cause  the  standard  input  to  the  uux  command  to  be  the  standard  input  to  the 
command-string. 

For  example,  the  command 

uux  **!difT  usg!/usr/dan/fl  pwba!/a4/dan/fl  >  Ifi.diff’* 

will  get  the  fl  files  from  the  usg  and  pwba  machines,  execute  a  diff  command  and  put  the  results 
in  fl.diff  in  the  local  directory. 

Any  special  shell  characters  such  as  <>;[  should  be  quoted  either  by  quoting  the  entire 
command-string,  or  quoting  the  special  characters  as  individual  arguments. 

OPTIONS 

— r  don’t  start  uucjco,  just  queue  the  job. 

—xn  set  debugging  level  to  n. 

—n  don’t  return  any  indication  by  mail  of  success  or  failure  of  the  job. 

—z  return  an  indication  by  mail  only  if  the  job  fails. 

— gj?  set  service  grade  or  classification  to  x.  The  default  is  A. 

FILES 

/usr/spool/uucp  spool  directory 

/usr/Iib/uucp/*other  data  and  programs 

SEE  ALSO 

uucp(lC) 

D,  A.  Nowitz,  Uucp  Implementation  Description 
WARNING 

An  installation  may,  and  for  security  reasons  generally  will,  limit  the  list  of  commands  executable 
on  behalf  of  an  incoming  request  from  uua?.  Typically,  a  restricted  site  will  permit  little  other 
than  the  receipt  of  mail  via  utiz. 

BUGS 

Only  the  first  command  of  a  shell  pipeline  may  have  a  system- name!.  All  other  commands  are 
executed  on  the  system  of  the  first  command. 

The  use  of  the  shell  metacharacter  ♦  will  probably  not  do  what  you  want  it  to  do. 

The  shell  tokens  «  and  »  are  not  implemented. 

There  is  no  notification  of  denial  of  execution  on  the  remote  machine. 
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NAME 

val  —  validate  SCCS  file 

SYNOPSIS 

/usr/sccs/val  — 

/usr/Bccs/val  [  — 8  ]  (  —tSID  \  |  — mname  ]  (  —ytype  ]  file  ... 

DESCRIPTION 

Val  determines  if  the  specified  file  is  an  SCCS  file  meeting  the  characteristics  specified  by  the 
optional  argument  list.  Arguments  to  val  may  appear  in  any  order. 

Val  has  a  special  argument,  — ,  which  causes  reading  of  the  standard  input  until  an  end-of-file 
condition  is  detected.  Each  line  read  is  independently  processed  as  if  it  were  a  command  line 
argument  list. 

Val  generates  diagnostic  messages  on  the  standard  output  for  each  command  line  and  file  pro¬ 
cessed  and  also  returns  a  single  8-bit  code  upon  exit  as  described  below. 

OPTIONS 

Options  apply  independently  to  each  named  file  on  the  command  line. 

—8  Silence  diagnostic  messages  normally  generated  for  errors  detected  while  processing  the 
specified  files. 

—rSlD  The  argument  value  SID  (5CCS  /Dentification  String)  is  an  SCCS  delta  number.  A  check 
is  made  to  determine  if  the  SID  is  ambiguous  (for  instance,  rl  is  ambiguous  because  it 
physically  does  not  exist  but  implies  1.1,  1.2,  etc.  which  may  exist)  or  invalid  (for 
instance,  rl.O  or  rl.1.0  are  invalid  because  neither  case  can  exist  as  a  valid  delta 
number).  If  the  SID  is  valid  and  not  ambiguous,  a  check  is  made  to  determine  if  it  actu¬ 
ally  exists. 

— m  name 

name  is  compared  with  the  SCCS  %M%  keyword  in  file. 

-ytype 

type  is  compared  with  the  SCCS  %Y%  keyword  in  file. 

The  8-bit  code  returned  by  val  is  a  disjunction  of  the  possible  errors,  that  is,  can  be  interpreted 
as  a  bit  string  where  (moving  from  left  to  right)  set  bits  are  interpreted  as  follows: 

bit  0  =  missing  file  argument; 

bit  1  =  unknown  or  duplicate  option; 

bit  2  =  corrupted  SCCS  file; 

bit  3  =  can’t  open  file  or  file  not  SCCS; 

bit  4  =  SID  is  invalid  or  ambiguous; 

bit  5  =  SID  does  not  exist; 

bit  6  =  %Y%,  —y  mismatch; 

bit  7  =  %M%,  — m  mismatch; 

Note  that  val  can  process  two  or  more  files  on  a  given  command  line  and  In  turn  can  process 
multiple  command  lines  (when  reading  the  standard  input).  In  these  cases  an  aggregate  code  is 
returned  —  logical  OR  of  the  codes  generated  for  each  command  line  and  file  processed. 

SEE  ALSO 

sccs(l),  admin(l),  delta(l),  get(l),  prs(l). 

Source  Code  Control  System  in  Programming  Tools  for  the  Sun  Workstation. 

DIAGNOSTICS 

Use  help{\)  for  explanations. 

BUGS 

Val  can  process  up  to  50  files  on  a  single  command  line.  Any  number  above  50  will  produce  a 
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core  dump. 


o 


374 


Last  change:  6  March  1984 


Sun  Release  2.0 


VAX(l) 


USER  COMMANDS 


VAX(l) 


NAME 

vax  —  is  current  machine  a  vax 
SYNOPSIS 


if  vax;  then  •••;  fl 

(Bh) 

if  {  vax  }  then 

endif 

(csh) 

DESCRIPTION 

The  vax  command  is,  on  VAX’en,  the  same  as  true(l);  on  Sun  Workstations  and  other  machines 
it  is  the  same  as  /alse(l). 

SEE  ALSO 

false(l),  sun(l),  true(l) 
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NAME 

vfontinfo  —  inspect  and  print  out  information  about  UNDC  fonts 
SYNOPSIS 

vfontinfo  I  —V  ]  fontname  [  characters  ] 

DESCRIPTION 

Vfontinfo  allows  you  to  examine  a  font  in  the  UNIX  format.  It  prints  out  all  the  information  in 
the  font  header  and  information  about  every  non-null  (width  >  0)  glyph.  This  can  be  used  to 
make  sure  the  font  is  consistent  with  the  format. 

The  fontname  argument  is  the  name  of  the  font  you  wish  to  inspect.  It  writes  to  standard  out¬ 
put.  If  it  can’t  find  the  file  in  your  working  directory,  it  looks  in  /usrfliblvfont  (the  place  most 
of  the  fonts  are  kept). 

The  characters,  if  given,  specify  certain  characters  to  show.  If  omitted,  the  entire  font  is  shown. 

If  the  -V  (verbose)  flag  is  used,  the  bits  of  the  glyph  itself  are  shown  as  an  array  of  X’s  and 
spaces,  in  addition  to  the  header  information. 

SEE  ALSO 

vpr(l),  vfont(5) 

The  Berkeley  Font  Catalog 
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NAME 

vgrind  —  grind  nice  listings  of  programs 
SYNOPSIS 

vgrind  I  -f  ]  [  -  I  I  -t  ]  [  -n  I  I  -X  ]  I  -W  ]  [  -en  |  \  -h  header  ]  |  — d  file  |  [  —llanguaQe  ] 
filename  grind  command**  ****  Vgrind  —  make  formatted  C  listings** 

DESCRIPTION 

Vgrind  formats  the  program  sources  which  are  file  arguments  in  a  nice  style  using  lroff{l).  Com¬ 
ments  are  placed  in  italics,  keywords  in  bold  face,  and  the  name  of  the  current  function  is  listed 
down  the  margin  of  each  page  as  it  is  encountered. 

Vgrind  runs  in  two  basic  modes,  filter  mode  or  regular  mode.  In  filter  mode  vgrind  acts  as  a 
filter  in  a  manner  similar  to  ^4/(1).  The  standard  input  is  passed  directly  to  the  standard  output 
except  for  lines  bracketed  by  the  ^ru^-iike  macros: 

.vS  -  starts  processing 

.vE  -  ends  processing 

These  lines  are  formatted  as  described  above.  The  output  from  this  filter  can  be  passed  to  troff 
for  output.  There  need  be  no  particular  ordering  with  €^n(l)  or  ^6/(1). 

In  regular  mode  vgrind  accepts  input  files,  processes  them,  and  passes  them  to  troff{l)  for  out¬ 
put. 

In  both  modes  vgrind  passes  any  lines  beginning  with  a  decimal  point  without  conversion. 
OPTIONS 

— f  force  filter  mode. 

—  take  from  standard  input  (default  if  — f  is  specified). 

— t  similar  to  the  same  option  in  troff,  that  is,  formatted  text  goes  to  the  standard  output. 

— n  do  not  make  keywords  boldface. 

—X  output  the  index  file  in  a  ‘pretty’  format.  The  index  file  itself  is  produced  whenever 
vgrind  is  run  with  a  file  called  index  in  the  current  directory.  The  index  of  function 
definitions  can  then  be  run  off  by  giving  vgrind  the  — x  option  and  the  file  index  as  argu¬ 
ment. 

— W  force  output  to  the  (wide)  Versatec  printer  rather  than  the  (narrow)  Varian. 

— B  specifies  a  point  size  to  use  on  output  (exactly  the  same  as  the  argument  of  a  troff  .ps 

(point  size)  request. 

— h  specifies  a  particular  header  to  put  on  every  output  page  (default  is  the  file  name). 

— d  specifies  an  alternate  language  definitions  file  (default  is  fusrjlib/vgrindefs), 

—I  specifies  the  language  to  use.  Currently  known  are  C  (— Ic  the  default),  CSH  (— Icsh), 

ICON  (-11),  ISP  (-1),  LDL  (-1LDL),  MODEL  (-Im),  PASCAL  (-Ip),  RATFOR  (-Ir),  and 
SHELL  (-Ish). 

FILES 

index  file  where  source  for  index  is  created 

/usr/lib/tmac/tmac.vgrind  macro  package 

/usr/lib/vfontedpr  preprocessor 

/usr/lib/vgrindefs  language  descriptions 

BUGS 

Vfontedpr  assumes  that  a  certain  programming  style  is  followed: 
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For  C  —  function  names  can  be  preceded  on  a  line  only  by  spaces,  tabs,  or  an  asterisk.  The 
parenthesized  arguments  must  also  be  on  the  same  line. 

For  PASCAL  —  function  names  need  to  appear  on  the  same  line  as  the  keywords  function  or  pro¬ 
cedure. 

If  these  conventions  are  not  followed,  the  indexing  and  marginal  function  name  comment 
mechanisms  will  fail. 

More  generally,  arbitrary  formatting  styles  for  programs  mostly  look  bad.  The  use  of  spaces  to 
align  source  code  fails  miserably;  if  you  plan  to  vgrind  your  program  you  should  use  tabs.  This  is 
somewhat  inevitable  since  the  font  used  by  vgrind  is  variable  width. 

The  mechanism  of  in  recognizing  functions  should  be  used  here. 
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NAME 

vi  —  screen  oriented  (visual)  display  editor  based  on  ex 
SYNOPSIS 

vl  I  — R  ]  [  — r  ]  [  — t  I  [  -k-command  |  [  — x  |  (  — wnnn  ]  [—l\JiU.., 

DESCRIPTION 

Vi  (visual)  is  a  display  oriented  text  editor  based  on  ez(l),  Ez  and  vi  are  in  fact  the  same  text 
editor;  it  is  possible  to  get  to  the  command  mode  of  ez  from  within  vi  and  vice-versa. 

OPTIONS 

— R  edit  the  file  in  read-only  state.  You  can  achieve  the  same  effect  with  the  view  command. 
— r  recover  the  indicated  files  after  a  crash. 

— t  tag  edit  the  file  containing  the  tag  tag,  A  tags  database  must  have  been  built  previously 
using  the  ctags{\)  command. 

•^command 

start  the  editing  session  by  executing  command, 

— wnnn 

set  the  default  window  (number  of  lines  on  your  terminal)  to  nnn —  this  is  useful  if  you 
are  dialling  into  the  system  over  a  slow  'phone  line. 

—x  prompt  for  a  key  to  be  used  in  encrypting  the  file  being  edited. 

—1  set  up  for  editing  LISP  programs. 

FILES 

See  ez{l), 

SEE  ALSO 

ex  (1),  edit  (1),  “Vi  Quick  Reference”  card, 

Using  vi,  the  Visual  Display  Editor  in 

Editing  and  Tezt  Processing  on  the  Sun  Workstation, 

BUGS 

Software  tabs  using  "T  work  only  immediately  after  the  autoindent. 

Left  and  right  shifts  on  intelligent  terminals  don’t  make  use  of  insert  and  delete  character  opera¬ 
tions  in  the  terminal. 

The  wrapmargin  option  can  be  fooled  since  it  looks  at  output  columns  when  blanks  are  typed.  If 
a  long  word  passes  through  the  margin  and  onto  the  next  line  without  a  break,  then  the  line 
won’t  be  broken. 

Repeating  a  change  which  wraps  over  the  margin  when  wrapmargin  is  in  effect  doesn’t  generally 
work  well:  sometimes  it  just  makes  a  mess  of  the  change,  and  sometimes  even  leaves  you  in  insert 
mode.  A  way  to  work  around  the  problem  is  to  replicate  the  changes  using  yank  and  put. 

Insert/delete  within  a  line  can  be  slow  if  tabs  are  present  on  intelligent  terminals,  since  the  termi¬ 
nals  need  help  in  doing  this  correctly. 

Saving  text  on  deletes  in  the  named  buffers  is  somewhat  inefficient. 

The  source  command  does  not  work  when  executed  as  tsouree;  there  is  no  way  to  use  the 
:append^  :change,  and  dniert  commands,  since  it  is  not  possible  to  give  more  than  one  line  of 
input  to  a  :  escape.  To  use  these  on  a  :gIobal  you  must  Q  to  ez  command  mode,  execute  them, 
and  then  reenter  the  screen  editor  with  vi  or  open. 

When  using  the  — r  option  to  recover  a  file,  you  must  write  the  recovered  text  before  quitting  or 
you  will  lose  it.  Vi  does  not  prevent  you  from  exiting  without  writing  unless  you  make  changes. 
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RESTRICTIONS 

The  encryption  facilities  of  vi  arc  not  available  on  software  shipped  outside  the  U.S. 
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NAME 

view  —  view  a  file  without  changing  it  using  the  vi  visual  editor 
SYNOPSIS 

view  I  — t  tag  ]  I  —r  I  [  -^command  |  [  — I  |  [  — wn  [  name 
DESCRIPTION 

View  uses  the  ui  (visual)  or  display  oriented  text  editor  to  browse  through  a  file  interactively 
without  actually  making  any  changes  to  the  file.  It  is  possible  to  get  to  the  command  mode  of  e;p 
from  within  view  and  vice-versa,  just  as  when  using  vi. 

FILES 

See  ex{l). 

SEE  ALSO 

ex  (1),  edit  (1),  vi(l),  “Vi  Quick  Reference”  card, 

Using  vi,  the  Visual  Display  Editor  in 

Editing  and  Text  Processing  on  the  Sun  Workstation. 
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NAME 

vIp  —  Format  Lisp  programs  to  be  printed  with  nroff,  vtro£f,  or  troff 

SYNOPSIS 

vlp  I  — p  pointsize  |  [  — d  ]  [  — f  ][—!][  — v  ]  [  — T  title!  |  filel  [  — T  titled  ]  file2  ... 

DESCRIPTION 

Vlp  formats  the  named  files  so  that  they  can  be  run  through  nroff,  vtroff,  or  troff  to  produce  list¬ 
ings  that  line-up  and  are  attractive.  The  first  non-blank  character  of  each  line  is  lined-up  verti¬ 
cally,  as  in  the  source  file.  Comments  (text  beginning  with  a  semicolon)  are  printed  in  italics. 
Each  function’s  name  is  printed  in  bold  face  next  to  the  function.  This  format  makes  Lisp  code 
look  attractive  when  it  is  printed  with  a  variable  width  font. 

Normally,  vlp  works  as  a  filter  and  sends  its  output  to  the  standard  output.  However,  the  — v 
switch  pipes  the  output  directly  to  vtroff.  If  no  files  are  specified,  then  vlp  reads  from  the  stan¬ 
dard  input. 

The  following  options  are  available: 

—p  The  — p  switch  changes  the  size  of  the  text  from  its  default  value  of  8  points  to  one  of  6, 
8,  10,  or  12  points.  Once  set,  the  point  size  is  used  for  all  subsequent  files.  This  point 
size  does  not  apply  to  embedded  text  (sec  —/below). 

— d  The  — d  switch  puts  vlp  into  debugging  mode. 

— f  Vlp  has  a  filtered  mode  in  which  all  lines  are  passed  unmodified,  except  those  lines 

between  the  directives  -Lb  and  .Le.  This  mode  can  be  used  to  format  Lisp  code  that  is 
embedded  in  a  document.  The  directive  .Ls  takes  an  optional  argument  that  gives  the 
point  size  for  the  embedded  code.  If  not  size  is  specified,  the  size  of  the  surrounding  text 
is  used. 

—1  The  —1  switch  prevents  vlp  from  placing  labels  next  to  functions.  This  switch  is  useful 
for  embedded  Lisp  code,  where  the  labels  would  be  distracting. 

—V  This  switch  cause  vlp  to  send  its  output  to  vtroff  rather  than  the  standard  output. 

— T  A  title  to  be  printed  on  each  page  may  be  specified  by  using  the  — T  switch.  The  — T 

switch  applies  only  to  the  next  file  name  given.  Titles  are  not  printed  for  embedded  text 
(see  — f,  above).  This  switch  may  not  be  used  if  vlp  is  reading  from  the  standard  input. 

FILES 

/usr/Iib/vlpmacs  troff/nroff  macros 

SEE  ALSO 

vgrind(l),  lisp(l) 

BUGS 

vlp  transforms  \  into  \\  so  that  it  will  be  printed  out.  Hence,  troff  commands  cannot  be  embed¬ 
ded  in  Lisp  code. 
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NAME 

vplot  —  plot  graphics  on  the  Versatec 
SYNOPSIS 

vplot  [  —  W  ]  I  —V  ]  [  — b  tpr-arg  |  file 
DESCRIPTION 

Vplot  reads  plot{S)  format  graphics  input  from  the  file  specified  by  file  (standard  input  if  no  file 
is  specified)  and  produces  a  plot  on  the  Varian  or  Versatec. 

OPTIONS 

— W  force  output  to  the  (wide)  Versatec  printer  rather  than  the  standard  Versatec  printer. 

force  output  to  the  standard  Versatec  printer. 

-“b  lpr~arg 

arg  (the  next  argument  on  the  command  line)  specifies  extra  arguments  to  /pr(l). 

SEE  ALSO 

plot(lG),  Ipr(l),  plot(5) 
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NAME 

vpr,  vprm,  vpq,  vprint  —  raster  printer/plotter  spooler 
SYNOPSIS 

vpr  (  — W  1  [  — 1 1  [  — V  j  [  — t  (  —1234  font  |  )  [  — w  |  (  — ]  [  — m  ]  [  name  ... ) 
vprm  [  id  ...  ]  [  filename  ...  )  [  owner  ...  ] 

vpq 

vprint  [  — W  ]  file  ... 

DESCRIPTION 

Vpr  causes  the  named  files  to  be  queued  for  printing  or  typeset  simulation  on  one  of  the  available 
raster  printer/plotters.  If  no  files  are  named,  the  standard  input  is  read.  By  default  the  input  is 
assumed  to  be  line  printer-like  text.  For  very  wide  plotters,  the  input  is  run  through  the  filter 
/usr/lib/sidebyside  giving  it  an  argument  of  — wlOd  which  arranges  it  four  pages  adjacent  with 
90  column  lines  (the  rest  is  for  the  left  margin).  Since  there  are  8  lines  per  inch  in  the  default 
printer  font,  vpr  thus  produces  86  lines  per  page  (the  top  and  bottom  lines  are  left  blank). 

The  following  options  are  available: 

—I  Print  the  input  in  a  more  literal  manner.  Page  breaks  are  not  inserted,  and 

most  control  characters  (except  format  effectors:  \n,  \f,  etc.)  are  printed  (many 
control  characters  print  special  graphics  not  in  the  ASCII  character  set.)  Tab 
and  underline  processing  is  still  done.  If  this  option  is  not  given,  control  charac¬ 
ters  which  are  not  format  effectors  are  ignored,  and  page  breaks  are  inserted 
after  an  appropriate  number  of  lines  have  been  printed  on  a  page. 

— W  Queues  files  for  printing  on  a  wide  output  device,  if  available.  Normally,  files 

are  queued  for  printing  on  a  narrow  output  device. 

—1234  Specifies  a  font  to  be  mounted  on  font  position  >.  The  daemon  will  construct  a 

.railmag  file  referencing  /usr/tib/vfont/name.size. 

— m  Report  by  mail{l)  when  printing  is  complete. 

— w  (Applicable  only  to  wide  output  devices.)  Do  not  run  the  input  through  sideby- 

side.  Such  processing  has  been  done  already,  or  full  (440  character)  printer 
width  is  desired. 

—vtwidth  Use  width  width  rather  than  90  for  sidebyside. 

—V  Use  the  filter  /usr/libjvraet  to  convert  the  vectors  to  raster.  The  named  files 

must  be  a  parameter  and  vector  file  (in  that  order)  created  by  p/(?f(3X)  routines. 

— t  Use  the  filter  /usr/lib/veat  to  typeset  the  input  on  the  printer/plotter.  The 

input  must  have  been  generated  by  troff{l)  run  with  the  — t  option.  This  is  not 
normally  run  directly  to  wide  output  devices,  since  it  is  wasteful  to  run  only  one 
page  across.  The  program  vtroff{l)  is  normally  used  and  arranges,  using  vsort 
for  printing  to  occur  four  pages  across,  conserving  paper. 

Vprm  removes  entries  from  the  raster  device  queues.  The  id,  filename  or  owner  should  be  that 
reported  by  vpq.  All  appropriate  files  will  be  removed.  Both  queues  are  always  searched.  The  id 
of  each  file  removed  from  the  queue  will  be  printed. 

Vpq  prints  the  queues.  Each  entry  in  the  queue  is  printed  showing  the  owner  of  the  queue  entry, 
an  identification  number,  the  size  of  the  entry  in  characters,  and  the  file  which  is  to  be  printed. 
The  id  is  useful  for  removing  a  specific  entry  from  the  printer  queue  using  vprm 

Vprint  is  a  shell  script  which  prV  a  copy  of  each  named  file  on  one  of  the  electrostatic 
printer /plotters.  The  files  are  normally  printed  on  a  narrow  device;  — W  option  causes  them  to 
be  printed  on  a  wide  device. 
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FILES 

/usr/spool/v?d/* 

/usr/lib/v?d 

/usr/lib/vpd 

/usr/lib/vpf 

/usr/lib/*vcat 

/usr/lib/vrast 

/usr/lib/sidebyside 


device  spool  areas 
daemons 

Versatec  daemon 

filter  for  printer  simulation 

filter  for  typeset  simulation 

filter  for  plot 

filter  for  wide  output 


SEE  ALSO 

troff(l),  vfont(5),  vp(4),  pti(l),  vtroff(l),  p!ot{3X) 

BUGS 

The  I’s  (one’s)  and  Vs  (lower-case  el’s)  in  a  Benson-Varian’s  standard  character  set  look  very 
similar;  caution  is  advised. 

A  versatec’s  hardware  character  set  is  rather  ugly.  Vjprtn^  should  use  one  of  the  constant  width 
fonts  to  produce  prettier  listings. 
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NAME 

Yswap  —  convert  a  foreign  font  file 
SYNOPSIS 

/usr/lib/vflwap  |  — r  | 

DESCRIPTION 

Without  the  -r  option,  vswap  translates  its  standard  input  (which  must  be  a  vfoni  file  in  the 
reversed-byte  order)  into  a  locally  correct  vfoni  file  on  its  standard  output.  With  the  -r  option, 
V8wap  translates  its  standard  input  (which  must  be  a  vfoni  file  in  the  local-byte  order)  Into  a 
byte-reversed  vfoni  file  on  its  standard  output. 

The  UNIX  vfoni  representation  for  fonts  is  a  binary  file  containing  machine-dependent  elements 
—  short  (16- bit)  integers,  in  particular.  There  are  (at  least)  two  common  ways  of  representing  a 
16-bit  integer,  A  program  compiled  on  a  VAX  will  expect  the  VAX  format,  while  the  same  pro¬ 
gram  compiled  on  a  Motorola  68000  will  expect  68000  format.  Vewap  can  be  used  to  convert 
font  files  created  on  a  VAX  to  the  format  required  to  use  them  on  the  Sun.  It  can  also  convert 
Sun- for  mat  font  files  to  VAX  format  (with  the  — r  option).  Since  the  font  files  are  in  the  byte 
order  of  the  local  machine,  programs  which  access  the  font  files  don’t  need  to  be  concerned  with 
byte-swapping  issues.  This  could  be  considered  a  bug. 

SEE  ALSO 

troff(l),  vfont(5) 

BUGS 

A  machine-independent  font  format  should  be  defined. 
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NAME 

vtroff  —  troll  to  a  raster  plotter 
SYNOPSIS 

vtroff  [  — w  ]  j  — P  majorfont  j  |  —123  minorfont  j  |  —llenffth  [  [  — x  ]  troff  arguments 
DESCRIPTION 

Vtroff  runs  troff(l)  sending  its  output  through  various  programs  to  produce  typeset  output  on  a 
raster  plotter  such  as  a  Benson-Varian  or  or  a  Versatec.  The  — W  option  specifies  that  a  wide 
output  device  be  used;  the  default  is  to  use  a  narrow  device.  The  —1  (lower  case  1)  option  causes 
the  output  to  be  split  onto  successive  pages  every  length  inches  rather  than  the  default  11”. 

The  default  font  is  a  Hershey  font.  If  some  other  font  is  desired  you  can  give  a  — F  argument 
and  then  the  font  name.  This  will  place  normal,  italic  and  bold  versions  of  the  font  on  positions 
1,  2,  and  3.  To  place  a  font  only  on  a  single  position,  you  can  give  an  argument  of  the  form  — n 
and  the  minor  font  name.  A  .r  will  be  added  to  the  minor  font  name  if  needed.  Thus  ‘‘vtroff 
—ms  paper”  will  set  a  paper  in  the  Hershey  font,  while  “vtroff  -F  nonie  —ms  paper”  will  set  the 
paper  in  the  (sans  serif)  nonie  font.  The  —x  option  asks  for  exact  simulation  of  photo-typesetter 
output.  (I.e.  using  the  width  tables  for  the  C.A.T.  photo-typesetter) 

FILES 

/usr/lib/tmac/tmac.vcat  default  font  mounts  and  bug  fixes 

/usr/lib/fontinfo/*  fixes  for  other  fonts 

/usr/lib/vfont  directory  containing  fonts 

SEE  ALSO 

troff(l),  vfont(5),  vpr(l) 

BUGS 

Since  some  macro  packages  work  correctly  only  if  the  fonts  named  R,  I,  B,  and  S  are  mounted, 
and  since  the  Versatec  fonts  have  different  widths  for  individual  characters  than  the  fonts  found 
on  the  typesetter,  the  following  dodge  was  necessary:  If  you  don’t  use  the  “.fp”  troff  directive 
then  you  get  the  widths  of  the  standard  typesetter  fonts  suitable  for  shipping  the  output  of  troff 
over  the  network  to  the  computer  center  A  machine  for  phototypesetting.  If,  however,  you 
remount  the  R,  I,  B  and  S  fonts,  then  you  get  the  width  tables  for  the  Versatec. 
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NAME 

vwidth  —  make  troll  width  table  for  a  font 
SYNOPSIS 

/usr/ltb/vwldth  fontfih  pointsize  >  ftzz.e 
ee  -c  ftzz.c 

mv  ftzz.o  /usr/llb/font/ftzz 
DESCRIPTION 

Vwidth  translates  from  the  width  information  stored  in  the  vfont  style  format  to  the  format 
expected  by  troff.  Troff  wants  an  object  file  in  a.out(5)  format.  (This  fact  does  not  seem  to  be 
documented  anywhere.)  Troff  should  look  directly  in  the  font  file  but  it  doesn’t. 

Vwidth  should  be  used  after  editing  a  font  with  fed(l).  It  is  not  necessary  to  use  vwidth  unless 
you  have  made  a  change  that  would  affect  the  width  tables.  Such  changes  include  numerically 
editing  the  width  field,  adding  a  new  character,  and  moving  or  copying  a  character  to  a  new 
position.  It  is  not  always  necessary  to  use  vwidth  if  the  physical  width  of  the  glyph  (e.g.  the 
number  of  columns  in  the  bit  matrix)  has  changed,  but  if  it  has  changed  much  the  logical  width 
should  probably  be  changed  and  vwidth  run. 

Vwidth  produces  a  C  program  on  its  standard  output.  This  program  should  be  run  through  the 
C  compiler  and  the  object  (that  is,  the  .o  file)  saved.  The  resulting  file  should  be  placed  in 
/usr/lib/font  in  the  file  ftzz  where  is  a  one  or  two  letter  code  that  is  the  logical  (internal  to  troff) 
font  name.  This  name  can  be  found  by  looking  in  the  file  /usr/lib/fortinfo//nome*  where  /name 
is  the  external,  name  of  the  font. 

SEE  ALSO 

fed(l),  vfont(5),  troff(l),  vtroff(l) 

BUGS 

Produces  the  C  file  using  obsolete  syntax  that  the  portable  C  compiler  complains  about. 
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NAME 

w  —  who  is  on  and  what  they  are  doing 

SYNOPSIS 

w  I  ~*h  ]  j  — B  I  [  user  ] 

DESCRIPTION 

W  displays  a  summary  of  the  current  activity  on  the  system,  including  what  each  user  is  doing. 
The  heading  line  shows  the  current  time  of  day,  how  long  the  system  has  been  up,  the  number  of 
users  logged  into  the  system,  and  the  load  averages.  The  load  average  numbers  give  the  number 
of  jobs  in  the  run  queue  averaged  over  1,  5  and  15  minutes. 

The  fields  displayed  are:  the  users  login  name,  the  name  of  the  tty  the  user  is  on,  the  time  of  day 
the  user  logged  on  (in  hoursrminutes),  the  idle  time  —  that  is,  the  number  of  minutes  since  the 
user  last  typed  anything  (in  hoursrminutes),  the  CPU  time  used  by  all  processes  and  their  children 
on  that  terminal  (in  minutesrseconds),  the  CPU  time  used  by  the  currently  active  processes  (in 
minutesrseconds),  the  name  and  arguments  of  the  current  process. 

If  a  user  name  is  included,  output  is  restricted  to  that  user. 

OPTIONS 

— h  Suppress  the  heading. 

— B  Produce  a  short  form  of  output.  In  the  short  form,  the  tty  is  abbreviated,  the  login  time 

and  cpu  times  are  left  off,  as  are  the  arguments  to  commands. 

—1  Produce  a  long  form  of  output,  which  is  the  default. 

EXAMPLE 

angel%  w 

7:36am  up  6  days,  16:45,  1  users,  load  average:  0.20,  0.23,  0.18 
User  tty  login®  idle  JCPU  PCPU  what 

henry  console  7:10am  1  10:05  4:31  w 

angel% 

FILES 

/etc/utmp 

/dev/kmem 

/dev/drum 

SEE  ALSO 

who(l),  ps(l),  utmp(5) 

BUGS 

The  notion  of  the  ‘current  process’  is  muddy.  The  current  algorithm  is  ‘the  highest  numbered 
process  on  the  terminal  that  is  not  ignoring  interrupts,  or,  if  there  is  none,  the  highest  numbered 
process  on  the  terminal’.  This  fails,  for  example,  in  critical  sections  of  programs  like  the  shell 
and  editor,  or  when  faulty  programs  running  in  the  background  fork  and  fail  to  ignore  interrupts. 
In  cases  where  no  process  can  be  found,  w  prints 

The  CPU  time  is  only  an  estimate,  in  particular,  if  someone  leaves  a  background  process  running 
after  logging  out,  the  person  currently  on  that  terminal  is  ‘charged’  with  the  time. 

Background  processes  are  not  shown,  even  though  they  account  for  much  of  the  load  on  the  sys¬ 
tem. 

Sometimes  processes,  typically  those  in  the  background,  are  printed  with  null  or  garbaged  argu¬ 
ments.  In  these  cases,  the  name  of  the  command  is  printed  in  parentheses. 

W  does  not  know  about  the  new  conventions  for  detecting  background  jobs.  It  will  sometimes 
find  a  background  job  instead  of  the  right  one. 
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NAME 

wait  —  await  completion  of  process 

SYNOPSIS 

wait 

DESCRIPTION 

Wait  until  all  processes  started  with  ft  or  bg  have  completed,  and  report  on  abnormal  termina¬ 
tions. 

Because  the  wait{2)  system  call  must  be  executed  in  the  parent  process,  the  Shell  itself  executes 
wait,  without  creating  a  new  process. 

SEE  ALSO 

sh(l),  csh(l) 

BUGS 

Not  all  the  processes  of  a  3-  or  more-stage  pipeline  are  children  of  the  Shell,  and  thus  can’t  be 
waited  for,  (This  bug  does  not  apply  to  caA(l).) 
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NAME 

wall  —  write  to  all  users 

SYNOPSIS 

wall  [  file  j 

DESCRIPTION 

Wall  reads  its  standard  input  until  an  end-of-fiie.  It  then  sends  this  message,  preceded  by 
‘Broadcast  Message  to  all  logged  in  users. 

The  sender  should  be  super-user  to  override  any  protections  the  users  may  have  invoked. 

FILES 

/dev/tty? 

/etc/utmp 

SEE  ALSO 

mesg(l),  write(l) 
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NAME 

wc  —  word  count 

SYNOPSIS 

wc  I  — Iwc  I  [file  ...  1 

DESCRIPTION 

Wc  counts  lines,  words,  and  characters  in  the  named  files,  or  in  the  standard  input  if  no  file 
names  appear.  A  word  is  a  string  of  characters  delimited  by  spaces,  tabs,  or  newlines. 

OPTIONS 

If  an  argument  beginning  with  one  of  ‘Iwc’  is  present,  the  specified  counts  are  selected  by  the 
letters: 

1  Count  lines, 

w  Count  words, 

c  Count  characters. 

The  default  is  —Iwc  (count  lines,  words,  and  characters). 

EXAMPLE 

angel%  wc  /u8r/inan/inaiil/{cBh.l,Bh.l,telnet.l) 

1876  11223  65895  /usr/man/manl/csh.l 

674  3310  20338  /usr/man/manl/sh.l 

260  1110  6834  /usr/man/manl/telnet.l 

2810  15643  93067  total 

angel% 
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NAME 

what  —  identify  the  version  of  fi!es 

SYNOPSIS 

wh&t  files 

DESCRIPTION 

What  searches  the  given  files  for  all  occurrences  of  the  pattern  that  ^e^{l)  substitutes  for  %Z% 
(this  is  @(#)  at  this  printing)  and  prints  out  what  follows  until  the  first  ",  >,  new-line,  \,  or  null 
character.  For  example,  if  the  C  program  in  file  programme  contains 

char  ident[]  =  "@(#)identification  information"; 
and  programme  is  compiled  to  yield  programme  and  a*oui,  the  command 
what  f.c  f.o  a.out 


will  print 

f.c: 

identification  information 

f.o: 

identification  information 

a.out: 

identification  information 

What  is  intended  to  be  used  in  conjunction  with  the  SCCS  command  which  automatically 

inserts  identifying  information,  but  it  can  also  be  used  where  the  information  is  inserted  manu¬ 
ally. 

SEE  ALSO 

sccs(l),  get(l),  help(l),  file(l). 

The  Source  Code  Control  Syetem  in  Programming  Toole  for  the  Sun  System 

DIAGNOSTICS 

Use  help{\)  for  explanations. 

BUGS 

It’s  possible  that  an  unintended  occurrence  of  the  pattern  @(#)  could  be  found  just  by  chance, 
but  this  causes  no  harm  in  nearly  all  cases. 
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NAME 

whatis  —  describe  what  a  command  is 

SYNOPSIS 

whatis  command  ««• 

DESCRIPTION 

WhaiU  looks  up  a  given  command  and  displays  the  header  line  from  the  manual  section.  You 
can  then  run  the  man(l)  command  to  get  more  information.  If  the  line  starts  *name(section) 
you  can  do  man  section  name  to  get  the  documentation  for  it.  Try  whatis  ed  and  then  you 
should  do  man  1  ed  to  get  the  manual  page  for  ed. 

Whatis  is  actually  just  the  —f  option  to  the  man(l)  command. 

FILES 

/usr/man/whatis  Data  base 

SEE  ALSO 

man(l),  catman(S) 
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NAME 

whereis  —  locate  source,  binary,  and/or  manual  for  program 
SYNOPSIS 

whereis  |  —Bbm  ]  |  — u  |  [  — BMS  dir  — f  ]  filename  ••• 

DESCRIPTION 

Whereie  locates  source/binary  and  manuals  sections  for  specified  files.  The  supplied  names  are 
first  stripped  of  leading  pathname  components  and  any  (single)  trailing  extension  of  the  form  .ext, 
for  example,  .c.  Prefixes  of  a.  resulting  from  use  of  source  code  control  are  also  dealt  with. 
Whereis  then  attempts  to  locate  the  desired  program  in  a  list  of  standard  places. 

OPTIONS 
--b 

— s 

— m 
— u 

-B 
-M 
--S 

-f 

EXAMPLE 

Find  all  files  in  fuarjbin  which  are  not  documented  in  /wsr/mun/muni  with  source  in 
{usrjsTcfcmd: 

angel%  cd  /usr/ucb 

angel%  whereis  — u  — M  /usr/man/manl  — S  /uer/Brc/cmd  — f  ♦ 

FILES 

/usr/src/* 

/usr/{doc,man}/* 

/lib,  /etc,  /usr/{lib,bin,ucb,o!d,new,local} 

BUGS 

Since  whereis  uses  cArfir(2)  to  run  faster,  pathnames  given  with  the  — M,  — S,  or  — B  must  be 
full;  that  is,  they  must  begin  with  a  ‘/\ 


Search  only  for  binaries. 

Search  only  for  sources. 

Search  only  for  manual  sections. 

Search  for  unusual  entries.  A  file  is  said  to  be  unusual  if  it  does  not  have  one  entry  of 
each  requested  type.  Thus  whereis  — m  — u  ♦  asks  for  those  files  in  the  current  direc¬ 
tory  which  have  no  documentation. 

Change  or  otherwise  limit  the  places  where  whereis  searches  for  binaries. 

Change  or  otherwise  limit  the  places  where  whereis  searches  for  manual  sections. 

Change  or  otherwise  limit  the  places  where  whereis  searches  for  sources. 

Terminates  the  last  directory  list  and  signals  the  start  of  file  names,  and  be  used 

when  any  of  the  — B,  — M,  or  — S  options  are  used. 
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NAME 

•which  —  locate  a  program  file  including  aliases  and  paths  (cah  only) 

SYNOPSIS 

•which  I  name  ]  ... 

DESCRIPTION 

Which  takes  a  list  of  names  and  looks  for  the  files  which  would  be  executed  had  these  names 
been  given  as  commands.  Each  argument  is  expanded  if  it  is  aliased,  and  searched  for  along  the 
user’s  path.  Both  aliases  and  path  are  taken  from  the  user’s  .cshrc  file. 

FILES 

"/.cshrc  source  of  aliases  and  path  values 

DIAGNOSTICS 

A  diagnostic  is  given  for  names  which  are  aliased  to  more  than  a  single  word,  or  if  an  executable 
file  with  the  argument  name  was  not  found  in  the  path. 

BUGS 

Only  aliases  and  paths  from  "/.cshrc  are  used;  importing  from  the  current  environment  is  not 
attempted.  Must  be  executed  by  a  csh,  since  only  csh’s  know  about  aliases. 

To  compensate  for  '/.cshrc  files  in  which  aliases  depend  upon  the  prompt  variable  being  set, 
which  sets  this  variable.  If  the  '/.cshrc  produces  output  or  prompts  for  input  when  prompt  is 
set,  which  may  produce  some  strange  results. 


o 


396 


Last  change:  25  March  1983 


Sun  Release  2.0 


WHO(l) 


USER  COMMANDS 


WHO(l) 


NAME 

who  —  who  is  on  the  system 
SYNOPSIS 

who  I  who-file  j  |  am  1 1 
DESCRIPTION 

Used  without  arguments,  wko  lists  the  login  name,  terminal  name,  and  login  time  for  each 
current  UNIX  user.  Who  gets  this  information  from  the  /eicfutmp  file. 

If  a  filename  argument  is  given,  the  named  file  is  examined  instead  of  /etc/utmp.  Typically  the 
named  file  is  /uer/adm/wtmpy  which  contains  a  record  of  all  logins  since  it  was  created.  In  this 
case,  who  lists  logins,  logouts,  and  crashes.  Each  login  is  listed  with  user  name,  terminal  name 
(with  '/devp  suppressed),  and  date  and  time.  Logouts  produce  a  similar  line  without  a  user 
name.  Reboots  produce  a  line  with  in  place  of  the  device  name,  and  a  fossil  time  indicating 
when  the  system  went  down.  Finally,  the  adjacent  pair  of  entries  and  indicate  the  system- 
maintained  time  just  before  and  after  a  date  command  changed  the  system's  idea  of  the  time. 

With  two  arguments,  as  in  ‘who  am  i’  (and  also  ‘who  are  you’),  who  tells  who  you  are  logged  in 
as:  it  displays  your  hostname,  login  name,  terminal  name,  and  login  time. 

EXAMPLES 

angel%  who  am  I 

angellhenry  ttypO  Apr  27  11:24 
angel% 

krypton%  who 
mktg  ttymO  Apr  27  11:11 
shannon  ttypO  Apr  27  11:25 

henry  ttypl  Apr  27  11:30 
krypton% 

FILES 

/etc/utmp 
SEE  ALSO 

whoami(l),  getuid(2),  w{l) 
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NAME 

whoami  —  display  effective  current  username 

SYNOPSIS 

whoami 

DESCRIPTION 

Whoami  displays  the  username  of  whoever  is  currently  logged  in.  Whoami  works  even  if  you  are 
logged  in  as  the  super-user,  while  ‘who  am  i’  does  not  since  it  gets  its  information  from  the 
/etc/utmp  file. 

FILES 

/etc/passwd  username  data  base 

SEE  ALSO 

who(l) 
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NAME 

whois  —  DARPA  Internet  user  name  directory  service 
SYNOPSIS 

whois  I  — h  host  I  identifier 
DESCRIPTION 

whois  searches  for  an  ARPAnet  directory  entry  for  an  identifier  which  is  either  a  name  (such  as 
“Smith”)  or  a  handle  (such  as  “SRI-NIC”).  You  can  force  a  name-only  search  by  preceeding  the 
name  with  a  period;  you  can  force  a  handle-only  search  by  preceeding  the  handle  with  an  excla¬ 
mation  point.  For  example,  typing: 

whois  Smith  looks  for  name  or  handle  SMITH, 

whois  ISRI-NIC  looks  for  handle  SRI-NIC  only, 

whois  .Smith,  John  looks  for  name  JOHN  SMITH  only. 

Adding  “...”  to  the  name  or  handle  argument  will  match  anything  from  that  point;  that  is, 
“ZU...”  will  match  ZUL,  ZUM,  etc. 

If  you  are  searching  for  a  group  or  organization  entry,  you  can  have  the  entire  membership  list  of 
the  group  displayed  with  the  record  by  preceeding  the  argument  with  an  astersik  (“♦”). 

You  may  of  course  use  an  exclamation  point  and  asterisk,  or  a  period  and  asterisk  together. 
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NAME 

write  —  write  to  another  user 


SYNOPSIS 

write  user  |  ttyname  j 

DESCRIPTION 

Write  copies  lines  from  your  standard  input  to  ttaer’s  screen. 

When  you  type  a  write  command,  the  person  you’re  writing  to  sees  a  message  like  this: 

Message  from  hostnamelyourname  on  yourttyname  at  hh:mm  .  .  . 

After  typing  the  write  command,  enter  the  text  of  your  message.  What  you  type  appears  line- 
by-line  on  the  other  user’s  screen.  Conclude  by  typing  an  end  of  file  indication  (*D)  or  an  inter¬ 
rupt.  At  this  point  write  displays  ‘EOT’  on  your  recipient’s  screen  and  exits. 

To  write  to  a  user  who  is  logged  in  more  than  once,  use  the  tfi/name  argument  to  indicate  the 
appropriate  terminal  name. 

You  can  grant  or  deny  other  users  permission  to  write  to  you  by  using  the  mesg  command 
(default  allows  writing).  Certain  commands,  nroff  and  pr(l)  in  particular,  don’t  allow  anyone  to 
write  to  you  while  you  are  using  them  in  order  to  prevent  messy  output. 

If  write  finds  the  character  ‘!’  at  the  beginning  of  a  line,  it  calls  the  shell  to  execute  the  rest  of 
the  line  as  a  command. 

Two  people  can  carry  on  a  conversation  by  write'ing  to  each  other.  When  the  other  person 
receives  the  message  indicating  you  are  writing  to  him,  he  can  then  write  back  to  you  if  he 
wishes.  However,  since  you  are  now  simultaneously  typing  and  receiving  messages,  you  end  up 
with  garbage  on  your  screen  unless  you  work  out  some  sort  of  scheduling  scheme  with  your 
partner.  You  might  try  the  following  conventional  protocol:  when  you  first  write  to  another 
user,  wait  for  him  to  write  back  before  starting  to  send.  Each  person  should  end  each  message 
with  a  distinctive  signal  —  -o-  (for  ‘over’)  is  standard  —  so  that  the  other  knows  when  to  begin 
a  reply.  To  end  your  conversation,  type  -oo-  (for  ‘over  and  out’)  before  finishing  the  conversa¬ 
tion. 


EXAMPLE 

Here  is  an  example  of  a  short  dialog  between  two  people  on  different  terminals.  Two  users  called 
Horace  and  Eudora  are  logged  in  on  a  system  called  Jones.  To  illustrate  the  process,  both  users’ 
screens  are  shown  side-by-side: 

Eudora’s  Terminal 


jones%  write  horace 

how  about  a  squash  game  tonightf  -o- 


Message  from  jonesihorace  on  tty03  at  17:06  ... 
I’m  playing  tiddlywinks  with  Carmeline  -o- 

How  about  the  beach  on  Sunday?  -o* 

Sorry,  I’m  washing  my  tent  that  day  -o- 

See  you  when  I  get  back  from  Peru  -oo- 
"D 

jones% 


I  hear  rack  of  llama  is  very  tasty  -oo- 

EOF 


Horace’s  Terminal 
Horace  is  staring  at  kis  screen 
Message  from  jonesfeudora  on  ttyOO  at  17:05  ... 
how  about  a  squash  game  tonight?  -o- 
jones%  write  eudora 

I’m  playing  tiddlywinks  with  Carmeline  -o* 


How  about  the  beach  on  Sunday?  -o- 

Sorry»  Pm  washing  my  tent  that  day  *o- 

See  you  when  I  get  back  from  Peru  -oo- 

EOF 

I  hear  rack  of  llama  is  very  tasty  -oo- 
•D 

jones% 
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USER  COMMANDS 


WRITE(l) 


FILES 

/etc/utmp 

/bin/sh 

SEE  ALSO 

mesg(l),  who(l),  mail(l),  talk(l) 


to  find  user 
to  execute  *!’ 
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USER  COMMANDS 


XSEND(l) 


NAME 

xsend,  xget,  enroll  —  secret  mail 

SYNOPSIS 

xsend  username 

xget 

enroll 

DESCRIPTION 

These  commands  implement  a  secure  communication  channel;  the  channel  is  like  mail{l),  but  no 
one  can  read  the  messages  except  the  intended  recipient.  The  method  embodies  a  public-key 
cryptosystem  using  knapsacks. 

To  receive  messages^  use  enroll ^  it  asks  you  for  a  password  that  you  must  subsequently  quote  in 
order  to  receive  secret  mail. 

To  receive  secret  mail,  use  xget.  It  asks  for  your  password,  then  gives  you  the  messages. 

To  send  secret  mail,  use  zsend  in  the  same  manner  as  the  ordinary  mail  command.  Unlike  mail, 
xsend  accepts  only  one  target.  A  message  announcing  the  receipt  of  secret  mail  is  also  sent  by 
ordinary  mail. 

FILES 

/usr/spool/secretmail/*.key  keys 
/usr/spool/secretmail/*.[0-9|  messages 

SEE  ALSO 

mail  (l) 

BUGS 

The  knapsack  public-key  cryptosystem  is  known  to  be  breakable. 

RESTRICTIONS 

These  facilities  are  not  available  on  software  shipped  outside  the  U.S. 
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NAME 

xstr  —  extract  strings  from  C  programs  to  implement  shared  strings 
SYNOPSIS 

XBtr  [  -V  ]  1  -c  I  I  -  I  [  file  1 
DESCRIPTION 

Xstr  maintains  a  file  called  strings  into  which  strings  in  component  parts  of  a  large  program  are 
hashed.  These  strings  are  replaced  with  references  to  this  common  area.  This  serves  to  imple- 
ment  shared  constant  strings,  most  useful  if  they  are  also  read-only. 

The  command 

xstr  — c  name 

extracts  the  strings  from  the  C  source  in  name,  replacing  string  references  by  expressions  of  the 
form  (&xstr(number))  for  some  number.  An  appropriate  declaration  of  xstr  is  prepended  to  the 
file.  The  resulting  C  text  is  placed  in  the  file  x.c,  to  then  be  compiled.  The  strings  from  this  file 
are  placed  in  the  strings  data  base  if  they  are  not  there  already.  Repeated  strings  and  strings 
which  are  suffixes  of  existing  strings  do  not  cause  changes  to  the  data  base. 

After  all  components  of  a  large  program  have  been  compiled  a  file  xs.c  declaring  the  common 
xstr  space  can  be  created  by  a  command  of  the  form 

xstr 

This  xs.c  file  should  then  be  compiled  and  loaded  with  the  rest  of  the  program.  If  possible,  the 
array  can  be  made  read-only  (shared)  saving  space  and  swap  overhead. 

Xstr  can  also  be  used  on  a  single  file.  A  command 

xstr  name 

creates  files  x.c  and  xs.c  as  before,  without  using  or  affecting  any  strings  file  in  the  same  direc¬ 
tory. 

It  may  be  useful  to  run  xstr  after  the  C  preprocessor  if  any  macro  definitions  yield  strings  or  if 
there  is  conditional  code  which  contains  strings  which  may  not,  in  fact,  be  needed.  Xstr  reads 
from  its  standard  input  when  the  argument  ’  is  given.  An  appropriate  command  sequence  for 
running  xstr  after  the  C  preprocessor  is: 

cc  — E  name.c  [  xstr  —c  — 
cc  — c  x.c 
mv  x.o  name.o 

Xstr  does  not  touch  the  file  strings  unless  new  items  are  added,  thus  make  can  avoid  remaking 
xs.o  unless  truly  necessary. 

OPTIONS 

— c  file  Take  C  source  text  from  file. 

—V  Verbose:  display  a  progress  report  indicating  where  new  or  duplicate  strings  were  found. 

FILES 

strings  Data  base  of  strings 

x.c  Massaged  C  source 

xs.c  C  source  for  definition  of  array  ‘xstr’ 

/tmp/xs*  Temp  file  when  ‘xstr  name’  doesn’t  touch  strings 
SEE  ALSO 

mkstr(l) 

BUGS 

If  a  string  is  a  suffix  of  another  string  in  the  data  base,  but  the  shorter  string  is  seen  first  by  xstr 
both  strings  will  be  placed  in  the  data  base,  when  just  placing  the  longer  one  there  will  do. 
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NAME 

yacc  —  yet  another  compiler-compiler 
SYNOPSIS 

yacc  [  — vd  ]  grammar 
DESCRIPTION 

Yacc  converts  a  context-free  grammar  into  a  set  of  tables  for  a  simple  automaton  which  executes 
an  LR(1)  parsing  algorithm.  The  grammar  may  be  ambiguous;  specified  precedence  rules  are 
used  to  break  ambiguities. 

The  output  file,  y.tab.c,  must  be  compiled  by  the  C  compiler  to  produce  a  function  named 
yyparse.  The  yyparse  function  must  be  loaded  with  the  lexical  analyzer  yylez,  as  well  as  main 
and  yyerror,  an  error  handling  routine.  These  routines  must  be  supplied  by  the  user;  /ear{l)  is 
useful  for  creating  lexical  analyzers  usable  by  yacc-produced  parsers. 

OPTIONS 

—V  Prepare  the  file  y. output  containing  a  description  of  the  parsing  tables  and  a  report  on 
conflicts  generated  by  ambiguities  in  the  grammar. 

— d  Generate  the  file  y.tab.h  with  the  define  statements  that  associate  the  yocc-assigned 

*token  codes'  with  the  user-declared  'token  names'  so  that  source  files  other  than  y»tab*c 
can  access  the  token  codes. 

FILES 

y.output 
y.tab.c 
y.tab.h 

yacc.tmp,  yacc.acts 
/usr/lib/yacepar 

SEE  ALSO 

lex{l) 

LR  Parsing  by  A.  V.  Aho  and  S.  C.  Johnson,  Computing  Surveys,  June,  1974 

Yacc  —  Yet  Another  Compiler  Compiler  ia  Programming  Tools  for  the  Sun  Workstation 

DIAGNOSTICS 

The  number  of  reduce-reduce  and  shift-reduce  conflicts  is  reported  on  the  standard  output;  a 
more  detailed  report  is  found  in  the  y.output  file.  Similarly,  if  some  rules  are  not  reachable  from 
the  start  symbol,  this  is  also  reported. 

BUGS 

Because  file  names  are  fixed,  at  most  one  yacc  process  should  be  active  in  a  given  directory  at  a 
time. 


description  of  parsing  tables  and  conflict  report 

output  parser 

defines  for  token  names 

temporary  files 

parser  prototype  for  C  programs 
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NAME 

yes  —  be  repetitively  affirmative 

SYNOPSIS 

yes  I  expletive  [ 

DESCRIPTION 

Yes  repeatedly  outputs  “y”,  or  if  expletive  is  given,  that  is  output  repeatedly.  Termination  is  by 
typing  an  interrupt  character. 


Sun  Release  2.0 


Last  change;  14  December  1983 


405 


YPCAT{1) 


USER  COMMANDS 
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NAME 

ypcat  -  print  values  in  a  YP  data  base 
SYNOPSIS 

ypcat  [  —a  ]  |  — k  |  I  — 1 1  |  — d  domainname  )  keyword 
DESCRIPTION 

Ypcat  prints  out  values  in  a  yellow  pages  (YP)  map  specified  by  a  keyword,  which  may  be  either 
a  mapname  or  an  abbreviated  mapname.  Since  ypcat  employs  YP  network  services,  the  location 
of  the  YP  server  cannot  be  supplied. 

Suppose  you  want  to  look  at  the  system  password  file.  Each  machine  has  a  file  letcjpaomd,  con¬ 
taining  only  a  small  amount  of  information.  The  network-wide  password  database  is  served  by 
the  YP,  and  holds  information  in  a  map  named  passwd.byname,  whose  abbreviated  name  is 
passwd.  Thus,  to  see  the  system  passwords,  you  type: 

ypcat  passwd 

Here  is  a  list  of  abbreviated  mapnames,  full  mapnames,  and  corresponding  system  files: 


passwd 

passwd. by  name 

/etc/passwd 

group 

group. byname 

/etc/group 

hosts 

hosts,  byaddr 

/etc/hosts 

networks 

networks,  byaddr 

/etc/networks 

services 

services.byname 

/etc /services 

protocols 

protocols. bynumber 

/etc/protocols 

netgroup 

netgroup 

/etc/netgroup 

A  list  of  all  maps  in  the  default  domain  can  be  seen  by  typing: 
ypcat  -k  ypmaps 

A  list  of  all  the  known  domains  can  be  seen  by  typing: 
ypcat  -d  yp_private  ypdomains 

OPTIONS 

—a  Get  all  the  key_value  pairs  back  from  the  YP,  including  private  symbols.  These  are 
uninteresting  to  almost  everyone. 

— k  Dump  the  keys,  as  well  as  the  values.  Keys  are  already  within  the  values  for  maps 

interesting  to  most  users.  Here  again,  the  extra  information  you  get  back  is  generally 
uninteresting.  Exceptions  are  those  maps  in  which  the  value  is  null  (that  is,  all  of  the 
information  in  the  map  is  in  the  keys),  or  maps  in  which  the  key  is  not  part  of  the  value. 
None  of  the  maps  derived  from  files  that  have  an  ASCII  version  in  /etc  fall  into  those 
classes. 

— t  Inhibit  translation  of  abbreviated  mapname  to  mapname.  For  example,  ypcat  — f  passwd 

will  fail  because  there  is  no  file  named  passwd,  while  ypcat  passwd  will  be  translated  to 
ypcat  passwd. byname.  The  purpose  of  this  option  is  to  let  you  specify  a  mapname  which 
is  also  a  keyword  name. 

— d  Used  to  specify  a  domain  other  that  the  default  domain.  The  default  domain  is  returned 
by  domainnam€{S).  The  default  domain  is  the  one  that  is  interesting  to  most  users. 

SEE  ALSO 

ypfiles(8),  yppush(8),  newpasswd(8) 
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NAME 

yppasswd  —  change  login  password  in  yellow  pages 

SYNOPSIS 

yppa«Bwd  I  name  j 

DESCRIPTION 

This  command  changes  (or  installs)  a  password  associated  with  the  user  name  (your  own  name 
by  default)  in  the  yellow  pages.  The  yellow  pages  password  may  be  different  from  the  one  on 
your  own  machine. 

Yppasswd  prompts  for  the  old  yellow  pages  password  and  then  for  the  new  one.  The  caller  must 
supply  both.  The  new  password  must  be  typed  twice,  to  forestall  mistakes. 

New  passwords  must  be  at  least  four  characters  long  if  they  use  a  sufficiently  rich  alphabet  and 
at  least  six  characters  long  if  monocase.  These  rules  are  relaxed  if  you  are  insistent  enough. 

Only  the  owner  of  the  name  or  the  super-user  may  change  a  password;  in  either  case  you  must 
prove  you  know  the  old  password. 

SEE  ALSO 

passwd(i),  ypfiles(5),  yppasswdd(8C) 

BUGS 

The  update  protocol  passes  all  the  information  to  the  server  in  one  rpc  call,  without  ever  looking 
at  it.  Thus  if  you  type  in  your  old  password  incorrectly,  you  will  not  be  notified  until  after  you 
have  entered  your  new  password. 
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NAME 

adventure  —  an  exploration  game 
SYNOPSIS 

/usr  /  games /adventure 

DESCRIPTION 

The  object  of  the  game  is  to  locate  and  explore  Colossal  Cave,  find  the  treasures  hidden  there, 
and  bring  them  back  to  the  building  with  you.  The  program  is  self-describing  to  a  point,  but 
part  of  the  game  is  to  discover  its  rules. 

To  terminate  a  game,  type  ‘quit’;  to  save  a  game  for  later  resumption,  type  ‘suspend’. 

BUGS 

Saving  a  game  creates  a  large  executable  file  instead  of  just  the  information  needed  to  resume 
the  game. 
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ARITHMETIC(6) 


NAME 

arithmetic  —  provide  drill  in  number  facts 
SYNOPSIS 

/uBr/games/arithmetlc  |  +— x/  )  [  range  ] 

DESCRIPTION 

Arithmetic  types  out  simple  arithmetic  problems,  and  waits  for  an  answer  to  be  typed  in.  If  the 
answer  is  correct,  it  types  back  *^Right!”,  and  a  new  problem.  If  the  answer  is  wrong,  it  replies 
“What?”,  and  waits  for  another  answer.  Every  twenty  problems,  it  publishes  statistics  on 
correctness  and  the  time  required  to  answer. 

To  quit  the  program,  type  an  interrupt  (delete). 

The  first  optional  argument  determines  the  kind  of  problem  to  be  generated;  +— x/  respectively 
cause  addition,  subtraction,  multiplication,  and  division  problems  to  be  generated.  One  or  more 
characters  can  be  given;  if  more  than  one  is  given,  the  different  types  of  problems  will  be  mixed 
in  random  order;  default  is  d — 

Range  is  a  decimal  number;  all  addends,  subtrahends,  differences,  multiplicands,  divisors,  and 
quotients  will  be  less  than  or  equal  to  the  value  of  range.  Default  range  is  10. 

At  the  start,  all  numbers  less  than  or  equal  to  range  are  equally  likely  to  appear.  If  the  respon¬ 
dent  makes  a  mistake,  the  numbers  in  the  problem  which  was  missed  become  more  likely  to  reap¬ 
pear. 

As  a  matter  of  educational  philosophy,  the  program  will  not  give  correct  answers,  since  the 
learner  should,  in  principle,  be  able  to  calculate  them.  Thus  the  program  is  intended  to  provide 
drill  for  someone  just  past  the  first  learning  stage,  not  to  teach  number  facts  de  novo.  For 
almost  all  users,  the  relevant  statistic  should  be  time  per  problem,  not  percent  correct. 
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NAME 

backgammon  —  the  game  of  backgammon 
SYNOPSIS 

backgammon  [  —  ]  [  n  r  w  b  pr  pw  pb  tterm  sfile  | 

DESCRIPTION 

Backgammon  lets  you  play  backgammon  against  the  computer  or  against  a  Triend'.  All  com¬ 
mands  only  are  one  letter,  so  you  don't  need  to  type  a  carriage  return,  except  at  the  end  of  a 
move.  Backgammon  is  mostly  self  documenting,  so  that  a  question  mark  (?)  will  usually  get  some 
help.  If  you  answer  *y'  when  backgammon  asks  if  you  want  the  rules,  you  will  get  text  explaining 
the  rules  of  the  game,  some  hints  on  strategy,  instruction  on  how  to  use  backgammon,  and  a 
tutorial  consisting  of  a  practice  game  against  the  computer.  A  description  of  how  to  use  back’ 
gammon  can  be  obtained  by  answering  ‘y'  when  it  asks  if  you  want  instructions.  The  possible 
arguments  for  backgammon  (most  are  unnecesary  but  some  are  very  convenient)  consist  of: 

n  don’t  ask  for  rules  or  instructions 
r  player  is  red  (implies  n) 
w  player  is  white  (implies  n) 
b  two  players,  red  and  white  (implies  n) 
pr  print  the  board  before  red’s  turn 
pw  print  the  board  before  white’s  turn 
pb  print  the  board  before  both  player’s  turn 

tterm  terminal  is  type  term,  uses  /etc/ termcap,  otherwise  uses  the  TERM  environment  vari¬ 
able. 

nfile  recover  previously  saved  game  from  file.  This  can  also  be  done  by  executing  the  saved 
file,  that  is,  typing  its  name  in  as  a  command. 

Arguments  may  be  optionally  preceded  by  a  —  sign.  Several  arguments  may  be  concatenated 
together,  but  not  after  ‘s’  or  ‘t’  arguments,  since  they  can  be  followed  by  an  arbitrary  string. 
Any  unrecognized  arguments  are  ignored.  An  argument  of  a  lone  —  gets  a  description  of  possible 
arguments. 

If  term  has  capabilities  for  direct  cursor  movement,  backgammon  ‘fixes’  the  board  after  each 
move,  so  the  board  does  not  need  to  be  reprinted,  unless  the  screen  suffers  some  horrendous 
malady.  Also,  any  ‘p’  option  will  be  ignored. 

QUICK  REFERENCE 

When  backgammon  prompts  by  typing  only  your  color,  type  a  space  or  carriage  return  to  roll,  or 
d  to  double 

p  to  print  the  board 

q  to  quit 

8  to  save  the  game  for  later 

When  backgammon  prompts  with  ’Move:’,  type 

p  to  print  the  board 

q  to  quit 

B  to  save  the  game 

or  a  move,  which  is  a  sequence  of 
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B-f  move  from  b  to  f 

fl/r  move  one  man  on  b  the  roll  r  separated  by  commas  or  spaces  and  ending  with  a  newline. 
Available  abbreviations  are 

B-fl-f2  means  B-fl|fl-f2 

B/rlr2  means  B/rl,B/r2 

Use  ‘b’  for  bar  and  'h’  for  home,  or  0  or  26  as  appropriate. 

FILES 

/usr/games/teachgammon  rules  and  tutorial 
/etc/ter mcap  terminal  capabilities 

BUGS 

Backgammon’s  sir needs  much  work. 
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NAME 

banner  —  print  large  banner  on  printer 
SYNOPSIS 

/ufir/games/banner  |  — wn  |  message 
DESCRIPTION 

Banner  prints  a  large,  high  quality  banner  on  the  standard  output.  If  the  message  is  omitted,  it 
prompts  for  and  reads  one  line  of  its  standard  input.  If  — w  is  given,  the  output  is  scrunched 
down  from  a  width  of  132  to  n  ,  suitable  for  a  narrow  terminal.  If  n  is  omitted,  it  defaults  to  80. 

The  output  should  be  printed  on  a  hard-copy  device,  up  to  132  columns  wide,  with  no  breaks 
between  the  pages.  The  volume  is  enough  that  you  want  a  printer  or  a  fast  hardcopy  terminal, 
but  if  you  are  patient,  a  dec  writer  or  other  300  baud  terminal  will  do. 

BUGS 

Several  ASCII  characters  are  not  defined,  notably  <,  >,  [,  ],  \,  {,  },  {,  and  Also,  the  char¬ 

acters  **,  \  and  &  are  funny  looking  (but  in  a  useful  way.) 

The  — w  option  is  implemented  by  skipping  some  rows  and  columns.  The  smaller  it  gets,  the 
grainier  the  output.  Sometimes  it  runs  letters  together. 
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NAME 

bed  —  convert  to  antique  media 
SYNOPSIS 

/usr/games/bed  text 
DESCRIPTION 

Bed  converts  the  literal  text  into  a  form  familiar  to  old-timers. 

SEE  ALSO 
dd(l) 
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NAME 

bdemos  —  demonstrate  Sun  Monochrome  Bitmap  Display 

SYNOPSIS 

/usr  /demo /bbalU 
/usr  /demo /bbounce 
/uBr  /demo /bdemos 
/usr  /demo /bj  ump 
/usr/demo/bphoto  file 
/usr  /demo/br  otcube 

DESCRIPTION 

Bdemos  is  a  collection  of  simple  demonstration  programs  for  the  Sun  Monochrome  Bitmap 
Display.  Each  program  is  briefly  described  below.  Unless  otherwise  noted^  each  program  should 
be  terminated  by  typing  the  appropriate  key  (usually  DELETE  or  "C)  to  generate  an  interrupt  sig¬ 
nal. 

bballs  colliding  balls  demo 
bbounce  bouncing  square  demo 
bdemoB  a  collection  of  demos 

This  program  has  a  menu  for  selection  of  several  different  demos.  After  typing  a  key 
to  select  a  particular  demo,  the  user  may  type  '"C  to  get  back  the  menu.  Type  ‘q’  to 
quit. 

bjump  simulated  jump  to  hyperspace 
bphoto  file 

dither  monochrome  image  file  to  bitmap  display 

Image  files  suitable  for  display  by  this  program  are  m  f  usr f  demo fbwpix, 
brotcube  black  ^nd  white  spinning  cube 

FILES 

/usr/demo/bwpix 

SEE  ALSO 

draw(6) 
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NAME 

boggle  —  play  the  game  of  boggle 
SYNOPSIS 

/uBr/games/boggle  [  +  !  [  ++  I 

DESCRIPTION 

This  program  is  intended  for  people  wishing  to  sharpen  their  skills  at  Boggle  (TM  Parker  Bros.). 
If  you  invoke  the  program  with  4  arguments  of  4  letters  each,  (e.g.  “boggle  appl  epie  moth 
erhd”)  the  program  forms  the  obvious  Boggle  grid  and  lists  all  the  words  from 
/usr /diet /words  found  therein.  If  you  invoke  the  program  without  arguments,  it  will  generate 
a  board  for  you,  let  you  enter  words  for  3  minutes,  and  then  tell  you  how  well  you  did  relative  to 
/usr/dlct/words. 

The  object  of  Boggle  is  to  find,  within  3  minutes,  as  many  words  as  possible  in  a  4  by  4  grid  of 
letters.  Words  may  be  formed  from  any  sequence  of  3  or  more  adjacent  letters  in  the  grid.  The 
letters  may  join  horizontally,  vertically,  or  diagonally.  However,  no  position  in  the  grid  may  be 
used  more  than  once  within  any  one  word.  In  competitive  play  amongst  humans,  each  player  is 
given  credit  for  those  of  his  words  which  no  other  player  has  found. 

In  interactive  play,  enter  your  words  separated  by  spaces,  tabs,  or  newlines.  A  bell  will  ring  when 
there  is  2:00,  1:00,  0:10,  0:02,  0:01,  and  0:00  time  left.  You  may  complete  any  word  started  before 
the  expiration  of  time.  You  can  surrender  before  time  is  up  by  hitting  ’break’.  While  entering 
words,  your  erase  character  is  only  effective  within  the  current  word  and  your  line  kill  character 
is  ignored. 

Advanced  players  may  wish  to  invoke  the  program  with  1  or  2  +’s  as  the  first  argument.  The 
first  +  removes  the  restriction  that  positions  can  only  be  used  once  in  each  word.  The  second  + 
causes  a  position  to  be  considered  adjacent  to  itself  as  well  as  its  (up  to)  8  neighbors. 
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BSUNCUBE(6) 


NAME 

bsuncube  —  view  3-D  Sun  logo 
SYNOPSIS 

/usr  /  demo/bsuncube 

DESCRIPTION 

Bsuncuht  allows  the  user  to  view  a  cube  from  various  positions  with  hidden  faces  removed.  The 
faces  of  the  cube  consist  of  the  Sun  logo.  The  viewing  position  is  selected  using  the  mouse. 
Using  the  SunCore  Graphics  Package,  a  3-D  projection  is  drawn  on  the  Sun  Monochrome  Bitmap 
Display, 

The  program  operates  in  two  modes:  DisplayObject  mode  and  SelectView  mode.  The  program 
starts  in  DisplayObject  mode. 

DisplayObject:  The  cube  is  displayed  in  3-D  perspective  with  hidden  faces  removed.  Type 
while  in  this  mode  to  exit  the  program.  Hit  mouse  button  3  to  switch  to  SelectView  mode. 

SelectView:  Schematic  projections  of  the  outline  of  the  cube  are  shown  and  the  mouse  is  used 
to  select  a  viewing  position.  Use  button  1  to  set  x  and  button  2  to  set  y  in  the  Front  View,  Use 
button  2  to  set  z  in  the  Top  View.  Hit  button  3  to  switch  to  DisplayObject  mode. 

The  view  shown  in  DisplayObject  mode  is  drawn  using  the  conventions  that  the  viewer  is  always 
looking  from  the  viewing  position  toward  the  center  of  the  cube  and  that  the  positive  y  axis  on 
the  screen  is  the  projection  of  the  positive  y  axis  in  3-D  cube  coordinates. 
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CANFIELD  (6) 


NAME 

canfield,  cfscores  —  the  solitaire  card  game  canfield 
SYNOPSIS 

/usr/games/canfield 
/usr  /games/cfscores 

DESCRIPTION 

If  you  have  never  played  solitaire  before,  it  is  recommended  that  you  consult  a  solitaire  instruc¬ 
tion  book.  In  Canfield,  tableau  cards  may  be  built  on  each  other  downward  in  alternate  colors. 
An  entire  pile  must  be  moved  as  a  unit  in  building.  Top  cards  of  the  piles  are  available  to  be  able 
to  be  played  on  foundations,  but  never  into  empty  spaces. 

Spaces  must  be  filled  from  the  stock.  The  top  card  of  the  stock  also  is  available  to  be  played  on 
foundations  or  built  on  tableau  piles.  After  the  stock  is  exhausted,  tableau  spaces  may  be  filled 
from  the  talon  and  the  player  may  keep  them  open  until  he  wishes  to  use  them. 

Cards  are  dealt  from  the  hand  to  the  talon  by  threes  and  this  repeats  until  there  are  no  more 
cards  in  the  hand  or  the  player  quits.  To  have  cards  dealt  onto  the  talon  the  player  types  ’ht*  for 
his  move.  Foundation  base  cards  are  also  automatically  moved  to  the  foundation  when  they 
become  available. 

The  command  ’c’  causes  canfield  to  maintain  card  counting  statistics  on  the  bottom  of  the 
screen.  When  properly  used  this  can  greatly  increase  ones  chances  of  winning. 

The  rules  for  betting  are  somewhat  less  strict  than  those  used  in  the  official  version  of  the  game. 
The  initial  deal  costs  $13.  You  may  quit  at  this  point  or  inspect  the  game.  Inspection  costs  $13 
and  allows  you  to  make  as  many  moves  as  is  possible  without  moving  any  cards  from  your  hand 
to  the  talon,  (the  initial  deal  places  three  cards  on  the  talon;  if  all  these  cards  are  used,  three 
more  are  made  available.)  Finally,  if  the  game  seems  interesting,  you  must  pay  the  final  install¬ 
ment  of  $26.  At  this  point  you  are  credited  at  the  rate  of  $5  for  each  card  on  the  foundation;  as 
the  game  progresses  you  are  credited  with  $5  for  each  card  that  is  moved  to  the  foundation. 
Each  run  through  the  hand  after  the  first  costs  $5.  The  card  counting  feature  costs  $1  for  each 
unknown  card  that  is  identified.  If  the  information  is  toggled  on,  you  are  only  charged  for  cards 
that  became  visible  since  it  was  last  turned  on.  Thus  the  maximum  cost  of  information  is  $34. 
Playing  time  is  charged  at  a  rate  of  $1  per  minute. 

With  no  arguments,  the  program  cfscores  prints  out  the  current  status  of  your  canfield  account. 
If  a  user  name  is  specified,  it  prints  out  the  status  of  their  canfield  account.  If  the  —a  flag  is 
specified,  it  prints  out  the  canfield  accounts  for  all  users  that  have  played  the  game  since  the 
database  was  set  up. 

FILES 

/usr/games/canfield  the  game  itself 

/usr /games/cfscores  the  database  printer 

/usr/games/lib/cfscores  the  database  of  scores 

BUGS 

It  is  impossible  to  cheat. 
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CHASE(6) 


NAME 

chase  —  Try  to  escape  to  killer  robots 
SYNOPSIS 

/uBr/gamcB/chase  [  nrobots  |  [  nfences  | 

DESCRIPTION 

The  object  of  the  game  chase  is  to  move  around  inside  of  the  box  on  the  screen  without  getting 
eaten  by  the  robots  chasing  and  without  running  into  anything. 

If  a  robot  runs  into  another  robot  while  chasing  you,  they  crash  and  leave  a  junk  heap.  If  a 
robot  runs  into  a  fence,  it  is  destroyed. 

If  you  can  survive  until  all  the  robots  are  destroyed,  you  have  won! 

If  you  do  not  specify  either  nrobots  or  nfences,  chase  will  prompt  you  for  them. 
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CHESS  (6) 


NAME 

chess  —  the  game  of  chess 

SYNOPSIS 

/usr  /games/chesa 

DESCRIPTION 

Chess  is  a  computer  program  that  plays  class  D  chess.  Moves  may  be  given  either  in  standard 
(descriptive)  notation  or  in  algebraic  notation.  The  symbol  ‘d-’  is  used  to  specify  check;  ‘o-o’  and 
‘o-o-o’  specify  castling.  To  play  black,  type  ‘first’;  to  print  the  board,  type  an  empty  line. 

Each  move  is  echoed  in  the  appropriate  notation  followed  by  the  program’s  reply. 

DIAGNOSTICS 

The  most  cryptic  diagnostic  is  *eh?’  which  means  that  the  input  was  syntactically  incorrect. 

FILES 

/usr/games/lib/chess.book  book  of  opening  moves 

BUGS 

Pawns  may  be  promoted  only  to  queens. 
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NAME 

chesstool  —  window- based  front-end  to  chess  program 
SYNOPSIS 

chesstool  [  ckess^program  \ 

DESCRIPTION 

Chesstool  is  a  window-based  front-end  to  the  program.  Used  without  options,  chesstool 

uses  /usrl gamesf  chess;  you  can  designate  any  alternate  program  which  uses  the  same  command 
syntax  as  cAe^s(6)  with  the  che8s_program  argument. 

When  chesstool  starts  up,  it  displays  a  large  window  with  three  subwindows.  The  first  subwin¬ 
dow  displays  messages  —  ‘'Illegal  move’\  for  example.  The  second  subwindow  is  an  options 
subwindow;  options  are  described  below.  The  final  subwindow  is  a  chessboard  display  with  white 
and  black  pieces  and  two  (advisory  only)  timekeeping  clocks. 

Make  your  moves  with  the  mouse:  select  a  piece  by  positioning  the  arrow  cursor  over  the  piece 
and  pressing  the  left  mouse  button  down,  then  drag  the  piece  to  the  destination  square,  and 
release  the  button.  The  cursor  will  then  turn  to  an  hourglass  icon  while  the  system  plays. 

Options  in  the  options  subwindow  may  be  selected  with  either  the  left  or  middle  mouse  buttons. 
These  options  are: 

(Last  Play)  Show  the  last  play  made. 

(Undo)  Undo  your  last  move  and  the  machine’s  response. 

Once  the  game  is  over,  it  is  not  possible  to  restart  it,  so  undo  will  update  the 
board,  but  the  game  cannot  be  continued  from  that  position. 

[Flash]  Flash  when  the  machine  has  completed  its  move. 

In  flash  mode,  if  the  chesstool  is  open,  the  piece  moved  by  the  system  on  its 
play  will  flash  until  you  make  your  move.  If  the  chesstool  is  iconic,  the  entire 
icon  will  flash  when  the  machine  has  made  its  move.  Thus  you  can  'Close* 
the  chesstool  and  be  alerted  when  it’s  your  turn  to  move.  To  turn  flash 
mode  off,  select  flash  again. 

(Machine  White)  Start  a  new  game  with  the  machine  playing  white. 

(Human  White)  Start  a  new  game  with  the  machine  playing  black. 

There  are  two  moves  which  are  special:  castling  and  capturing  a  pawn  en  passant  To  castle, 
move  the  king  only.  The  position  of  the  rook  will  automatically  be  updated.  Since  the  king 
moves  two  squares  when  castling,  the  move  is  unambiguous.  To  capture  en  passant^  move  the 
pawn  to  the  square  occupied  by  the  opposing  pawn  which  will  be  captured. 

SEE  ALSO 

chess(6) 
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NAME 

ching  —  the  book  of  changes  and  other  cookies 
SYNOPSIS 

/usr/gaines/ehing  |  hexagram  ] 

DESCRIPTION 

The  /  Ching  or  Book  of  Changes  is  an  ancient  Chinese  oracle  that  has  been  in  use  for  centuries  as 
a  source  of  wisdom  and  advice. 

The  text  of  the  oracle  (as  it  is  sometimes  known)  consists  of  sixty-four  hexagramo,  each  symbol¬ 
ized  by  a  particular  arrangement  of  six  straight  ( - )  and  broken  ( - )  lines.  These  lines  have 

values  ranging  from  six  through  nine,  with  the  even  values  indicating  the  broken  lines. 

Each  hexagram  consists  of  two  major  sections.  The  Judgement  relates  specifically  to  the 
matter  at  hand  (E.g.,  “It  furthers  one  to  have  somewhere  to  go.”)  while  the  Image  describes  the 
general  attributes  of  the  hexagram  and  how  they  apply  to  one’s  own  life  (“Thus  the  superior  man 
makes  himself  strong  and  untiring.”). 

When  any  of  the  lines  has  the  value  six  or  nine,  it  is  a  moving  line;  for  any  such  line  there  is  an 
appended  judgement  which  becomes  significant.  Furthermore,  the  moving  lines  are  inherently 
unstable  and  change  into  their  opposites;  a  second  hexagram  (and  thus  an  additional  judgement) 
is  formed. 

Normally,  one  consults  the  oracle  by  fixing  the  desired  question  firmly  in  mind  and  then  casting  a 
set  of  changes  (lines)  using  yarrow— stalks  or  tossed  coins.  The  resulting  hexagram  will  be  the 
answer  to  the  question. 

Using  an  algorithm  suggested  by  S.  C.  Johnson,  the  UNIX  oracle  simply  reads  a  question  from 
the  standard  input  (up  to  an  EOF)  and  hashes  the  individual  characters  in  combination  with  the 
time  of  day,  process  id  and  any  other  magic  numbers  which  happen  to  be  lying  around  the  sys¬ 
tem.  The  resulting  value  is  used  as  the  seed  of  a  random  number  generator  which  drives  a  simu¬ 
lated  coin— toss  divination.  The  answer  is  then  piped  through  nroff  for  formatting  and  will 
appear  on  the  standard  output. 

For  those  who  wish  to  remain  steadfast  in  the  old  traditions,  the  oracle  will  also  accept  the 
results  of  a  personal  divination  using,  for  example,  coins.  To  do  this,  cast  the  change  and  then 
type  the  resulting  line  values  as  an  argument. 

The  impatient  modern  may  prefer  to  settle  for  Chinese  cookies;  try  /ortane(6). 

SEE  ALSO 

It  furthers  one  to  see  the  great  man. 

DIAGNOSTICS 

The  great  prince  issues  commands. 

Founds  states,  vests  families  with  fiefs. 

Inferior  people  should  not  be  employed. 

BUGS 

Waiting  in  the  mud 

Brings  about  the  arrival  of  the  enemy. 

If  one  is  not  extremely  careful. 

Somebody  may  come  up  from  behind  and  strike  him. 

Misfortune. 
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NAME 

colordemos  —  demonstrate  Sun  Color  Graphics  Display 

SYNOPSIS 

/uBr/demo/cballB 
/uBr/demo/cdraw 
/usr/demo/cphoto  file 
/usT  /demo/cplpes 
/uBr /demo /cshowmap  file 
/usr  /demo /csno  w 
/u8r/demo/c8uncube 
/  UBr  /demo/cBunlogo 
/  UBr  /  demo /cvlsl 

DESCRIPTION 

Colordemos  is  a  collection  of  simple  demonstration  programs  for  the  Sun  Color  Graphics  Display. 
Each  program  is  briefly  described  below.  To  exit  each  program,  send  an  interrupt  signal  by  typ¬ 
ing  the  appropriate  key  (usually  CONTROL  c). 

cballB  colliding  balls  on  color  display 

cdraw  draw  on  the  color  display;  see  rfr8u;(6)  for  an  explanation  of  how  to  use  cdraw. 
cphoto  file 

display  dithered  color  file  on  color  display.  Files  suitable  for  display  are  in 
/  usr/  demo/ colorpix. 

cpipeB  colliding  pipes  on  color  display 
cshowmap  file 

display  maps.  Files  suitable  for  display  are  in  /usr/ demo /segments. 
cBnow  color  kaleidoscope 
CBuncube  multicolored  Sun  logo 
csunlogo  shaded  Sun  logo 
cvlsl  color  vlsi  layout  demo 

FILES 

/usr /demo/color  pix 
/usr/demo/segments 
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NAME 

cribbage  —  the  card  game  cribbage 
SYNOPSIS 

/usr/games/cribbage  [  — req  ]  name  ... 

DESCRIPTION 

Cribbage  plays  the  card  game  cribbage,  with  cribbage  playing  one  hand  and  the  user  the  other. 
Cribbage  initially  asks  the  user  if  the  rules  of  the  game  are  needed  —  if  so,  cribbage  displays  the 
appropriate  section  from  According  to  Hoyle  with  more{l). 

OPTIONS 

— c  Provide  an  explanation  of  the  correct  score  when  the  player  makes  mistakes  scoring  his 

hand  or  crib.  This  is  especially  useful  for  beginning  players. 

— q  Print  a  shorter  form  of  all  messages  —  this  is  only  recommended  for  users  who  have 

played  the  game  without  specifying  this  option. 

—r  Instead  of  asking  the  player  to  cut  the  deck,  cribbage  will  randomly  cut  the  deck. 

PLAYING  CRIBBAGE 

Cribbage  first  asks  the  player  whether  he  wishes  to  play  a  short  game  (“once  around^,  to  61)  or  a 
long  game  (“twice  around”,  to  121).  A  response  of  ‘s’  results  in  a  short  game,  any  other  response 
plays  a  long  game. 

At  the  start  of  the  first  game,  cribbage  asks  the  player  to  cut  the  deck  to  determine  who  gets  the 
first  crib.  The  user  should  respond  with  a  number  between  0  and  51,  indicating  how  many  cards 
down  the  deck  is  to  be  cut.  The  player  who  cuts  the  lower  ranked  card  gets  the  first  crib.  If 
more  than  one  game  is  played,  the  loser  of  the  previous  game  gets  the  first  crib  in  the  current 
game. 

For  each  hand,  cribbage  first  prints  the  player’s  hand,  whose  crib  it  is,  and  then  asks  the  player 
to  discard  two  cards  into  the  crib.  The  cards  are  prompted  for  one  per  line,  and  are  typed  as 
explained  below. 

After  discarding,  cribbage  cuts  the  deck  (if  it  is  the  player’s  crib)  or  asks  the  player  to  cut  the 
deck  (if  it’s  its  crib);  in  the  later  case,  the  appropriate  response  is  a  number  from  0  to  39  indicat- 
ing  how  far  down  the  remaining  40  cards  are  to  be  cut. 

After  cutting  the  deck,  play  starts  with  the  non-dealer  (the  person  who  doesn’t  have  the  crib) 
leading  the  first  card.  Play  continues,  as  per  cribbage,  until  all  cards  are  exhausted.  Cribbage 
keeps  track  of  the  scoring  of  all  points  and  the  total  of  the  cards  on  the  table. 

After  play,  the  hands  are  scored.  Cribbage  requests  the  player  to  score  his  hand  (and  the  crib,  if 
it  is  his)  by  printing  out  the  appropriate  cards  (and  the  cut  card  enclosed  in  brackets).  Play  con¬ 
tinues  until  one  player  reaches  the  game  limit  (61  or  121). 

A  carriage  return  when  a  numeric  input  is  expected  is  equivalent  to  typing  the  lowest  legal  value; 
when  cutting  the  deck  this  is  equivalent  to  choosing  the  top  card, 

SPECIFYING  CARDS 

Cards  are  specified  as  rank  followed  by  suit.  The  ranks  may  be  specified  as  one  of  a,  2,  3,  4,  5, 
6,  7,  8,  3,  t,  J,  q,  and  k,  or  alternatively,  one  of  ace,  two,  three,  four,  five,  six,  seven,  eight, 
nine,  ten.  Jack,  queen,  and  king.  Suits  may  be  specified  as  s,  h,  d,  and  e,  or  alternatively  as 
spades,  hearts,  diamonds,  and  clubs.  A  card  may  be  specified  as  rank  suit,  or  rank  of  suit. 
If  the  single  letter  rank  and  suit  designations  are  used,  the  space  separating  the  suit  and  rank 
may  be  left  out.  Also,  if  only  one  card  of  the  desired  rank  is  playable,  typing  the  rank  is 
sufficient.  For  example,  if  your  hand  was  2h,  4d,  5c,  5h,  Jc,  kd  and  you  wanted  to  discard  the 
king  of  diamonds,  you  could  type  any  of  k,  king,  kd,  k  d,  kofd,  king  d,  king  of  d, 
k  diamonds,  k  of  diamonds,  king  diamonds,  or  king  of  diamonds. 


424 


Last  change:  7  March  1984 


Sun  Release  2.0 


CRIBBAGE(6) 


GAMES  AND  DEMOS 


CRIBBAGE(6) 


FILES 

/usr/games/cribbage 
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NAME 

draw  —  interactive  graphics  drawing 

SYNOPSIS 

/usr/demo/bdraw 
/  usr /demo  /cdraw 

DESCRIPTION 

The  draw  programs  are  menu-driven  programs  which  use  the  mouse,  keyboard,  bitmap  display 
and  optionally  the  color  display  to  draw  objects,  drag  them  around,  save  them  on  disk,  and  so 
on.  Bdraw  is  the  draw  program  for  the  black  and  white  display  and  cdraw  is  the  program  for 
driving  the  color  display. 

The  main  menu  items  are  selected  by  moving  the  mouse  cursor  and  pressing  the  left  mouse  but¬ 
ton.  To  redraw  the  display,  point  at  the  left  edge  of  the  main  menu  box  and  press  the  left  but¬ 
ton.  The  main  menu  items  are: 

New  Seg  xiate 

Open  a  new  translatable  segment.  A  segment  is  a  collection  of  attributes  and  primi¬ 
tives  (lines,  text,  polygons,  etc.).  A  translatable  segment  may  subsequently  be  posi¬ 
tioned. 

New  Seg  xform 

Open  a  new  transformable  segment.  A  transformable  segment  may  subsequently  be 
rotated,  scaled,  or  positioned. 

Delete  Seg 

To  delete  a  segment,  point  at  any  primitive  in  the  segment  and  press  the  left  button. 

Lines  To  add  line  primitives  to  the  currently  open  segment,  position  cursor,  press  the  left 
button,  ...  press  right  button  to  quit. 

Polygon  To  add  a  polygon  primitive  to  the  currently  open  segment,  position  the  cursor,  press 
the  left  button,  •••  press  the  right  button  to  terminate  the  boundary  definition. 
Polygons  are  filled  with  the  current  fill  attribute. 

Raster  To  add  a  raster  primitive  to  the  currently  open  segment,  position  the  cursor,  press  the 
left  button  to  reposition  the  box,  adjust  the  box  by  moving  the  mouse,  press  the  right 
button  to  create  the  raster  primitive  comprising  the  boxed  bitmap.  A  ‘rasterfile’  is 
also  created  on  disk  for  hardcopy  purposes  (see  JuBrf  include/ raster  file, h).  This 
‘rasterfile’  file  may  be  spooled  to  a  Versatec  printer /plotter  for  hardcopy  after  exiting 
from  the  draw  program.  The  command  to  do  this  is  Ipr  — v  rasterfile. 

Text  To  add  a  text  primitive  to  the  currently  open  segment,  position  cursor,  press  left  but¬ 
ton,  type  the  text  string  at  the  keyboard  (back  space  works),  hit  return.  Text  is 
drawn  with  the  current  text  attributes. 

Marker  To  add  marker  primitives  to  the  currently  open  segment,  position  cursor,  press  the 
left  button  to  place  marker,  ...  press  the  right  button  to  quit. 

Position  To  position  a  segment,  point  at  any  primitive  in  the  segment,  press  left  button,  posi¬ 
tion  the  segment,  press  right  button  to  quit. 

Rotate  To  rotate  a  transformable  segment,  point  at  any  primitive  in  the  segment,  press  left 
button,  move  mouse  to  rotate,  press  right  button  to  quit. 

Seale  To  scale  a  transformable  segment,  point  at  any  primitive  in  the  segment,  press  the  left 
button,  move  mouse  to  scale  in  x  or  y,  press  right  button  to  quit. 

Attributes 

This  item  brings  up  the  attribute  menu.  To  select  an  attribute  such  as  text  font, 
region  fill  texture  (color),  linestyle,  or  line  width,  point  at  the  item  and  press  the  left 
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button.  Point  at  the  left  edge  of  the  menu  box  to  quit. 

Save  Seg  To  save  a  segment  on  a  disk  file,  point  at  the  segment,  press  the  left  button,  type  the 
disk  file  name,  hit  return. 

Restore  Seg 

To  restore  a  previously  saved  segment  from  disk,  type  file  name,  hit  return. 

Exit  Exit  the  draw  program. 

BUGS 

Rasters  and  raster  text  do  not  scale  or  rotate.  If  segments  completely  overlap,  only  the  last  one 
drawn  may  be  picked  by  pointing  with  the  mouse.  This  also  applies  to  the  menu  segments! 
Therefore,  don’t  cover  them  up  with  polygons.  If  aborted  with  your  interrupt  character,  you 
must  give  the  ‘reset’  command  to  turn  keyboard  echo  back  on  and  to  reset  -cbreak.  Therefore, 
use  the  Exit  item  in  the  main  menu  to  exit  the  program. 
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NAME 

fish  —  play  "Go  Fish” 

SYNOPSIS 

/uar/games/fish 

DESCRIPTION 

Fisk  plays  the  game  of  “Go  Fish”,  a  children’s  card  game.  The  object  is  to  accumulate  ‘books’  of 
4  cards  with  the  same  face  value.  The  players  alternate  turns;  each  turn  begins  with  one  player 
selecting  a  card  from  his  hand,  and  asking  the  other  player  for  all  cards  of  that  face  value.  If  the 
other  player  has  one  or  more  cards  of  that  face  value  in  his  hand,  he  gives  them  to  the  first 
player,  and  the  first  player  makes  another  request.  Eventually,  the  first  player  asks  for  a  card 
which  is  not  in  the  second  player’s  hand:  he  replies  ‘GO  FISHI’  The  first  player  then  draws  a 
card  from  the  ‘pool’  of  undealt  cards.  If  this  is  the  card  he  had  last  requested,  he  draws  again. 
When  a  book  is  made,  either  through  drawing  or  requesting,  the  cards  are  laid  down  and  no 
further  action  takes  place  with  that  face  value. 

To  play  the  computer,  simply  make  guesses  by  typing  a,  2,  3,  4,  5,  6,  7,  8,  9,  10,  j,  q,  or  k  when 
asked.  Hitting  return  gives  you  information  about  the  size  of  my  hand  and  the  pool,  and  tells 
you  about  my  books.  Saying  ‘p’  as  a  first  guess  puts  you  into  ‘pro’  level;  the  default  is  pretty 
dumb. 
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NAME 

fortune  —  print  a  random,  hopefully  interesting,  adage 
SYNOPSIS 

/usr/games/fortune  [  —  |  (  — wsla  ) 

DESCRIPTION 

Fortune  with  no  arguments  prints  out  a  random  adage.  The  flags  mean: 

— -w  Waits  before  termination  for  an  amount  of  time  calculated  from  the  number  of  characters 
in  the  message.  This  is  useful  if  it  is  executed  as  part  of  the  logout  procedure  to  guarantee 
that  the  message  can  be  read  before  the  screen  is  cleared. 

— s  Short  messages  only. 

—I  Long  messages  only. 

—a  Choose  from  either  list  of  adages. 

FILES 

/usr/games/lib/fortunes.dat 
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NAME 

gammontool  —  play  a  game  of  backgammon 

SYNOPSIS 

gammontool  [  path  | 

DESCRIPTION 

Gammontool  paints  a  backgammon  board  on  the  screen,  and  then  lets  you  play  against  the  com¬ 
puter.  It  must  be  run  in  SunWindows.  The  optional  path  argument  specifies  an  alternate  move¬ 
generating  program,  which  must  be  specially  designed  to  run  with  gammontool. 

The  game  has  three  subwindows:  an  option  window  on  top,  a  message  window  in  the  middle,  and 
a  large  board  on  the  bottom.  The  buttons  in  the  option  window  are  used  to  restart,  double,  etc. 
The  message  window  has  two  lines:  the  first  tells  whose  turn  it  is,  and  the  second  displays  any 
errors  that  occur. 

The  initial  roll.  To  start  the  game,  roll  the  dice  to  determine  who  goes  first.  Move  the  mouse 
arrow  onto  the  board  and  click  the  left  button.  One  die  appears  on  each  side  of  the  board:  the 
die  on  the  left  is  yours,  and  the  die  on  the  right  is  the  computer’s.  If  your  roll  is  greater,  then 
you  move;  if  not,  the  computer  makes  a  move. 

Making  your  move.  When  it  is  your  turn,  “Your  move”  appears  in  the  message  window.  Place 
the  mouse  over  any  piece  of  your  color,  and  click  the  left  button.  While  holding  down  the  but¬ 
ton,  move  the  mouse  to  drag  the  piece;  the  piece  follows  the  mouse  until  you  release  the  button. 
The  tool  checks  each  move  and  does  not  allow  illegal  moves.  When  you  have  made  as  many 
moves  as  you  can,  the  computer  takes  its  turn;  after  it  finishes,  you  may  either  roll  again,  or 
double. 

Doubling.  To  double,  click  the  Double  button  in  the  option  window  and  wait  for  the  computer’s 
response.  If  the  computer  doubles  you,  a  message  is  displayed  and  you  must  answer  with  the 
Accept  Double  or  Refuse  Double  buttons.  The  Forfeit  button  can  also  be  used  to  refuse  a  double. 
If  the  game  is  doubled,  a  doubling  cube  with  the  proper  value  is  displayed  on  the  bar  strip.  If 
the  number  is  facing  up,  then  you  may  double  next.  If  the  number  is  upside  down,  it  is  the 
computer’s  turn  to  double. 

Other  buttom.  If  you  want  to  change  your  move  before  you  have  finished  it,  use  the  Redo  Move 
or  Redo  Entire  Move  buttons  in  the  option  window.  Redo  Entire  Move  replaces  all  of  the  pieces 
you  have  moved  so  that  you  can  redo  them  all.  Redo  Move  only  replaces  the  last  piece  you 
moved,  so  it  is  useful  when  you  roll  doubles  and  want  to  redo  only  the  last  piece  you  moved. 
Note  that  once  you  have  made  all  of  the  moves  your  roll  permits,  play  passes  immediately  to  the 
computer,  so  you  cannot  redo  the  very  last  move.  The  Show  Last  Move  button  allows  you  to  see 
the  last  move  again. 

Leaving  the  game.  If  you  want  to  quit  playing  backgammon,  use  the  Quit  button.  If  you  want 
to  forfeit  the  game,  use  the  Forfeit  button.  The  computer  penalizes  you  by  taking  a  certain 
number  of  points,  but  the  program  does  not  terminate. 

To  play  another  game  after  winning,  losing,  or  forfeiting,  click  either  the  Human  is  white  or 
Human  is  black  buttons,  depending  on  which  color  you  want.  Your  pieces  always  move  from  the 
top  right  to  the  bottom  right  of  the  board,  regardless  of  your  color.  As  an  additional  cue  as  to 
your  color,  your  dice  is  always  displayed  on  the  left  half  of  the  board. 

Log  file.  If  a  there  is  a  gammonlog  file  your  home  directory,  gammontool  keeps  a  log  of  the 
games  played.  Each  move  and  double  gets  recorded,  along  with  the  winners  and  accumulated 
scores. 

FILES 

~/gammonlog  log  of  games  played 
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BUGS 

The  default  strategy  used  by  the  computer  is  very  poor. 

If  a  move  uses  more  than  one  die  (for  instance  if  you  roll  5,  6  and  move  11  spaces  without  land¬ 
ing  in  the  middle)  it  is  unpredictable  where  the  piece  will  touch  down  at  in  the  middle.  The  pro¬ 
gram  will  always  make  the  move  if  possible,  but  if  two  midpoints  would  work  and  there  is  a  blot 
on  one  of  them,  it  is  much  better  to  explicitly  hit  the  blot  and  then  move  the  piece  the  rest  of  the 
way. 
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NAME 

hangman  —  Computer  version  of  the  game  hangman 


SYNOPSIS 

/usr  /  games /hangman 

DESCRIPTION 

In  hangman,  the  computer  picks  a  word  from  the  on-iine  word  list  and  you  must  try  to  guess  it. 
The  computer  keeps  track  of  which  letters  have  been  guessed  and  how  many  wrong  guesses  you 
have  made  on  the  screen  in  a  graphic  fashion. 


FILES 

/usr/dict /words  On-line  word  list 
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NAME 

mille  —  play  Mille  Domes 
SYNOPSIS 

/uBr/games/mllle  [  file  | 

DESCRIPTION 

Mille  plays  a  two-handed  game  reminiscent  of  the  Parker  Brother’s  game  of  Mille  Domes  with 
you.  The  rules  are  described  below.  If  a  file  name  is  given  on  the  command  line,  the  game  saved 
in  that  file  is  started. 

When  a  game  is  started  up,  the  bottom  of  the  score  window  will  contain  a  list  of  commands. 
They  are: 

P  Pick  a  card  from  the  deck.  This  card  is  placed  in  the  ‘P’  slot  in  your  hand. 

D  Discard  a  card  from  your  hand.  To  indicate  which  card,  type  the  number  of  the  card  in 

the  hand  (or  “P”  for  the  just-picked  card)  followed  by  a  carriage-return  or  space.  The 
carriage-return  or  space  is  required  to  allow  recovery  from  typos  which  can  be  very 
expensive,  like  discarding  safeties. 

U  Use  a  card.  The  card  is  again  indicated  by  its  number,  followed  by  a  carriage-return  or 
space. 

O  Toggle  ordering  the  hand.  By  default  off,  if  turned  on  it  will  sort  the  cards  in  your  hand 
appropriately.  This  is  not  recommended  for  the  impatient  on  slow  terminals. 

Q  Quit  the  game.  This  will  ask  for  confirmation,  just  to  be  sure.  Hitting  <DELETE>  (or 
<RUBOUT>)  is  equivalent. 

S  Save  the  game  in  a  file.  If  the  game  was  started  from  a  file,  you  will  be  given  an  oppor¬ 
tunity  to  save  it  on  the  same  file.  If  you  don’t  wish  to,  or  you  did  not  start  from  a  file, 
you  will  be  asked  for  the  file  name.  If  you  type  a  carriage-return  without  a  name,  the 
save  will  be  terminated  and  the  game  resumed. 

R  Redraw  the  screen  from  scratch.  The  command  "L  (control  *L*)  will  also  work. 

W  Toggle  window  type.  This  switches  the  score  window  between  the  startup  window  (with 
all  the  command  names)  and  the  end-of-game  window.  Using  the  end-of-game  window 
saves  time  by  eliminating  the  switch  at  the  end  of  the  game  to  show  the  final  score. 
Recommended  for  hackers  and  other  miscreants. 

If  you  make  a  mistake,  an  error  message  will  be  printed  on  the  last  line  of  the  score  window,  and 
a  bell  will  beep. 

At  the  end  of  each  hand  or  game,  you  will  be  asked  if  you  wish  to  play  another.  If  not,  it  will 
ask  you  if  you  want  to  save  the  game.  If  you  do,  and  the  save  is  unsuccessful,  play  will  be 
resumed  as  if  you  had  said  you  wanted  to  play  another  hand/game.  This  allows  you  to  use  the 
“S”  command  to  reattempt  the  save.  (The  game  itself  is  a  product  of  Parker  Brothers,  Inc.) 

SEE  ALSO 

curses(3X) 

CARDS 

Here  is  some  useful  information.  The  number  in  brackets  after  the  card  name  is  the  number  of 
that  card  in  the  deck: 
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Hazard 

Out  of  Gas  {2) 
Flat  Tire  |2] 
Accident  [2] 
Stop  [4| 

Speed  Limit  [3] 


Repair 

Gasoline  (6) 
Spare  Tire  [6| 
Repairs  [6| 

Go  [Hj 

End  of  Limit  |6l 


Safety 

Extra  Tank  |1| 
Puncture  Proof  [1] 
Driving  Ace  [l] 
Right  of  Way  jl) 


25  -  [10],  50  -  [10],  75  -  [10],  100  -  [12],  200  -  [4] 


RULES 

Object:  The  point  of  game  is  to  get  a  total  of  5000  points  in  several  hands.  Each  hand  is  a  race 
to  put  down  exactly  700  miles  before  your  opponent  does.  Beyond  the  points  gained  by  putting 
down  milestones,  there  are  several  other  ways  of  making  points. 

Overview:  The  game  is  played  with  a  deck  of  101  cards.  Didtance  cards  represent  a  number  of 
miles  traveled.  They  come  in  denominations  of  25,  50,  75,  100,  and  200.  When  one  is  played,  it 
adds  that  many  miles  to  the  player’s  trip  so  far  this  hand.  Hazard  cards  are  used  to  prevent 
your  opponent  from  putting  down  Distance  cards.  With  the  exception  of  the  speed  limit  card, 
they  can  only  be  played  if  your  opponent  has  a  Go  card  on  top  of  the  Battle  pile.  The  cards  are 
Out  of  Gas,  Accident,  Flat  Tire,  Speed  Limit,  and  Stop.  Remedy  cards  fix  problems  caused  by 
Hazard  cards  played  on  you  by  your  opponent.  The  cards  are  Gasoline,  Repairs,  Spare  Tire, 
End  of  Limit,  and  Go.  Safety  cards  prevent  your  opponent  from  putting  specific  Hazard  cards  on 
you  in  the  first  place.  They  are  Extra  Tank,  Driving  Ace,  Puncture  Proof,  and  Right  of  Way, 
and  there  are  only  one  of  each  in  the  deck. 

Board  Layout:  The  board  is  split  into  several  areas.  From  top  to  bottom,  they  are:  SAFETY 
AREA  (unlabeled):  This  is  where  the  safeties  will  be  placed  as  they  are  played.  HAND:  These 
are  the  cards  in  your  hand.  BATTLE:  This  is  the  Battle  pile.  All  the  Hazard  and  Remedy 
Cards  are  played  here,  except  the  Speed  Limit  and  End  of  Limit  cards.  Only  the  top  card  is 
displayed,  as  it  is  the  only  effective  one.  SPEED:  The  Speed  pile.  The  Speed  Limit  and  End  of 
Limit  cards  are  played  here  to  control  the  speed  at  which  the  player  is  allowed  to  put  down 
miles.  MILEAGE:  Miles  are  placed  here.  The  total  of  the  numbers  shown  here  is  the  distance 
traveled  so  far. 

Play:  The  first  pick  alternates  between  the  two  players.  Each  turn  usually  starts  with  a  pick 
from  the  deck.  The  player  then  plays  a  card,  or  if  this  is  not  possible  or  desirable,  discards  one. 
Normally,  a  play  or  discard  of  a  single  card  constitutes  a  turn.  If  the  card  played  is  a  safety, 
however,  the  same  player  takes  another  turn  immediately. 

This  repeats  until  one  of  the  players  reaches  700  points  or  the  deck  runs  out.  If  someone  reaches 
700,  they  have  the  option  of  going  for  an  Extension,  which  means  that  the  play  continues  until 
someone  reaches  1000  miles. 

Hazard  and  Remedy  Cards:  Hazard  Cards  are  played  on  your  opponent’s  Battle  and  Speed 
piles.  Remedy  Cards  are  used  for  undoing  the  effects  of  your  opponent’s  nastyness. 

Go  (Green  Light)  must  be  the  top  card  on  your  Battle  pile  for  you  to  play  any  mileage,  unless 
you  have  played  the  Right  of  Way  card  (see  below). 

Stop  is  played  on  your  opponent’s  Go  card  to  prevent  them  from  playing  mileage  until  they 
play  a  Go  card. 

Speed  Limit  is  played  on  your  opponent’s  Speed  pile.  Until  they  play  an  End  of  Limit  they 
can  only  play  25  or  50  mile  cards,  presuming  their  Go  card  allows  them  to  do  even  that. 

End  of  Limit  Is  played  on  your  Speed  pile  to  nullify  a  Speed  Limit  played  by  your  opponent. 
Out  of  Gas  is  played  on  your  opponent’s  Go  card.  They  must  then  play  a  Gasoline  card, 
and  then  a  Go  card  before  they  can  play  any  more  mileage. 

Flat  Tire  is  played  on  your  opponent’s  Go  card.  They  must  then  play  a  Spare  Tire  card, 
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and  then  a  Go  card  before  they  can  play  any  more  mileage. 

Accident  is  played  on  your  opponent’s  Go  card.  They  must  then  play  a  Repairs  card,  and 
then  a  Go  card  before  they  can  play  any  more  mileage. 

Safety  Cards:  Safety  cards  prevent  your  opponent  from  playing  the  corresponding  Hazard  cards 
on  you  for  the  rest  of  the  hand.  It  cancels  an  attack  in  progress,  and  always  entitles  the  player  to 
an  extra  turn. 

Right  of  Way  prevents  your  opponent  from  playing  both  Stop  and  Speed  Limit  cards  on  you. 
It  also  acts  as  a  permanent  Go  card  for  the  rest  of  the  hand,  so  you  can  play  mileage  as  long  as 
there  is  not  a  Hazard  card  on  top  of  your  Battle  pile.  In  this  case  only,  your  opponent  can  play 
Hazard  cards  directly  on  a  Remedy  card  besides  a  Go  card. 

Extra  Tank  When  played,  your  opponent  cannot  play  an  Out  of  Gas  on  your  Battle  Pile. 
Puncture  Proof  When  played,  your  opponent  cannot  play  a  Flat  Tire  on  your  Battle  Pile. 
Driving  Ace  When  played,  your  opponent  cannot  play  an  Accident  on  your  Battle  Pile. 

Distance  Cards:  Distance  cards  are  played  when  you  have  a  Go  card  on  your  Battle  pile,  or  a 
Right  of  Way  in  your  Safely  area  and  are  not  stopped  by  a  Hazard  Card.  They  can  be  played  in 
any  combination  that  totals  exactly  700  miles,  except  that  you  cannot  play  more  than  two  SOO 
mile  cards  in  one  hand.  A  hand  ends  whenever  one  player  gets  exactly  700  miles  or  the  deck 
runs  out.  In  that  case,  play  continues  until  neither  someone  reaches  700,  or  neither  player  can 
use  any  cards  in  their  hand.  If  the  trip  is  completed  after  the  deck  runs  out,  this  is  called 
Delayed  Action. 

Coup  Four4:  This  is  a  French  fencing  term  for  a  counter-thrust  move  as  part  of  a  parry  to  an 
opponents  attack.  In  Mille  Bornes,  it  is  used  as  follows:  If  an  opponent  plays  a  Hazard  card,  and 
you  have  the  corresponding  Safety  in  your  hand,  you  play  it  immediately,  even  before  you  draw. 
This  immediately  removes  the  Hazard  card  from  your  Battle  pile,  and  protects  you  from  that 
card  for  the  rest  of  the  game.  This  gives  you  more  points  (see  “Scoring”  below). 

Scoring:  Scores  are  totaled  at  the  end  of  each  hand,  whether  or  not  anyone  completed  the  trip. 
The  terms  used  in  the  Score  window  have  the  following  meanings: 

Milestones  Played:  Each  player  scores  as  many  miles  as  they  played  before  the  trip  ended. 
Each  Safety:  100  points  for  each  safety  in  the  Safety  area. 

All  4  Safeties:  300  points  if  all  four  safeties  are  played. 

Each  Coup  Four4:  300  points  for  each  Coup  Foure  accomplished. 

The  following  bonus  scores  can  apply  only  to  the  winning  player. 

Trip  Completed:  400  points  bonus  for  completing  the  trip  to  700  or  1000. 

Safe  Trip;  300  points  bonus  for  completing  the  trip  without  using  any  200  mile  cards. 
Delayed  Action:  300  points  bonus  for  finishing  after  the  deck  was  exhausted. 

Extension:  200  points  bonus  for  completing  a  1000  mile  trip. 

Shut-Out:  500  points  bonus  for  completing  the  trip  before  your  opponent  played  any  mileage 
cards. 

Running  totals  are  also  kept  for  the  current  score  for  each  player  for  the  hand  (Hand  Total), 
the  game  (Overall  Total),  and  number  of  games  won  (Games). 
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NAME 

monop  —  Monopoly  game 
SYNOPSIS 

/usr/games/monop  (  file  ) 

DESCRIPTION 

Monop  is  reminiscent  of  the  Parker  Brother’s  game  Monopoly,  and  monitors  a  game  between  1  to 
9  users.  It  is  assumed  that  the  rules  of  Monopoly  are  known.  The  game  follows  the  standard 
rules,  with  the  exception  that,  if  a  property  would  go  up  for  auction  and  there  are  only  two  sol¬ 
vent  players,  no  auction  is  held  and  the  property  remains  unowned. 

The  game,  in  effect,  lends  the  player  money,  so  it  is  possible  to  buy  something  which  you  cannot 
afford.  However,  as  soon  as  a  person  goes  into  debt,  he  must  *‘fix  the  problem”,  ».e.,  make  him¬ 
self  solvent,  before  play  can  continue.  If  this  is  not  possible,  the  player’s  property  reverts  to  his 
debtee,  either  a  player  or  the  bank.  A  player  can  resign  at  any  time  to  any  person  or  the  bank, 
which  puts  the  property  back  on  the  board,  unowned. 

Any  time  that  the  response  to  a  question  is  a  string,  e.g.,  a  name,  place  or  person,  you  can  type 
7’  to  get  a  list  of  valid  answers.  It  is  not  possible  to  input  a  negative  number,  nor  is  it  ever 
necessary. 


A  Summary  of  Commands: 

quit:  quit  game;  This  allows  you  to  quit  the  game.  It  asks  you  if  you’re  sure. 

print:  print  board:  This  prints  out  the  current  board.  The  columns  have  the  following 

meanings  (column  headings  are  the  same  for  the  where,  own  holdings,  and  hold¬ 
ings  commands): 

Name  The  first  ten  characters  of  the  name  of  the  square 
Own  The  number  of  the  owner  of  the  property. 

The  cost  of  the  property  (if  any) 

This  field  has  a  in  it  if  the  property  is  mortgaged 


Price 

Mg 

# 


If  the  property  is  a  Utility  or  Railroad,  this  is  the  number  of  such  owned  by 
the  owner.  If  the  property  is  land,  this  is  the  number  of  houses  on  It. 

Rent  Current  rent  on  the  property.  If  it  is  not  owned,  there  is  no  rent. 

where:  where  players  are:  Tells  you  where  all  the  players  are.  A  V  indicates  the  current 

player. 


own  holdings: 

List  your  own  holdings,  t.e.,  money,  get-out-of-jail-free  cards,  and  property. 

holdings:  holdings  list:  Look  at  anyone’s  holdings.  It  will  ask  you  whose  holdings  you  wish  to 
look  at.  When  you  are  finished,  type  "done”. 

shell:  shell  escape:  Escape  to  a  shell.  When  the  shell  dies,  the  program  continues  where  you 

left  off. 


mortgage: 

mortgage  property:  Sets  up  a  list  of  mortgageable  property,  and  asks  which  you  wish 
to  mortgage. 

unmortgage: 

unmortgage  property:  Unmortgage  mortgaged  property, 
buy:  buy  houses:  Sets  up  a  list  of  monopolies  on  which  you  can  buy  houses.  If  there  is 
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more  than  one,  it  asks  you  which  you  want  to  buy  for.  It  then  asks  you  how  many 
for  each  piece  of  property,  giving  the  current  amount  in  parentheses  after  the  pro¬ 
perty  name.  If  you  build  in  an  unbalanced  manner  (a  disparity  of  more  than  one 
house  within  the  same  monopoly),  it  asks  you  to  re-input  things. 

sell:  sell  houses:  Sets  up  a  list  of  monopolies  from  which  you  can  sell  houses,  it  operates  in 

an  analogous  manner  to  buy 

card:  card  for  jail:  Use  a  get-out-of-jail-free  card  to  get  out  of  jail.  If  you’re  not  in  jail,  or 

you  don^t  have  one,  it  tells  you  so. 

pay:  pay  for  jail:  Pay  $50  to  get  out  of  jail,  from  whence  you  are  put  on  Just  Visiting. 

Difficult  to  do  if  you’re  not  there. 

trade:  This  allows  you  to  trade  with  another  player.  It  asks  you  whom  you  wish  to  trade 

with,  and  then  asks  you  what  each  wishes  to  give  up.  You  can  get  a  summary  at  the 
end,  and,  in  all  cases,  it  asks  for  confirmation  of  the  trade  before  doing  it. 

resign:  Resign  to  another  player  or  the  bank.  If  you  resign  to  the  bank,  all  property  reverts 

to  its  virgin  state,  and  get-out-of-jail  free  cards  revert  to  the  deck. 

save:  save  game:  Save  the  current  game  in  a  file  for  later  play.  You  can  continue  play  after 

saving,  either  by  adding  the  file  in  which  you  saved  the  game  after  the  monop  com¬ 
mand,  or  by  using  the  restore  command  (see  below).  It  will  ask  you  which  file  you 
wish  to  save  it  in,  and,  if  the  file  exists,  confirm  that  you  wish  to  overwrite  it. 

restore:  restore  game:  Read  in  a  previously  saved  game  from  a  file.  It  leaves  the  file  intact. 

roll:  Roll  the  dice  and  move  forward  to  your  new  location.  If  you  simply  hit  the 

<RETURN>  key  instead  of  a  command,  it  is  the  same  as  typing  rolL 


FILES 

/usr/games/lib/cards.pck  Chance  and  Community  Chest  cards 

BUGS 

No  command  can  be  given  an  argument  instead  of  a  response  to  a  query. 
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NAME 

number  —  convert  Arabic  numerals  to  English 
SYNOPSIS 

/usr  /  games/number 
DESCRIPTION 

Number  copies  the  standard  input  to  the  standard  output,  changing  each  decimal  number  to  a 
fully  spelled  out  version. 
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NAME 

quiz  —  test  your  knowledge 
SYNOPSIS 

/uBr/games/qutz  [  — I  file  j  [  — t  |  |  category  1  category2  ] 

DESCRIPTION 

Quiz  gives  associative  knowledge  tests  on  various  subjects.  It  asks  items  chosen  from  category! 
and  expects  answers  from  categoryS.  If  no  categories  are  specified^  quiz  gives  instructions  and 
lists  the  available  categories. 

Quiz  tells  a  correct  answer  whenever  you  type  a  bare  newline.  At  the  end  of  input,  upon  inter¬ 
rupt,  or  when  questions  run  out,  quiz  reports  a  score  and  terminates. 

The  — t  flag  . specifies  ‘tutoriar  mode,  where  missed  questions  are  repeated  later,  and  material  is 
gradually  introduced  as  you  learn. 

The  —I  flag  causes  the  named  file  to  be  substituted  for  the  default  index  file.  The  lines  of  these 
files  have  the  syntax: 

line  =  category  newline  |  category  line 
category  =  alternate  |  category  ‘j’  alternate 
alternate  =  empty  |  alternate  primary 
primary  =  character  |  category  *]’  |  option 
option  «  category 

The  first  category  on  each  line  of  an  index  file  names  an  information  file.  The  remaining 
categories  specify  the  order  and  contents  of  the  data  in  each  line  of  the  information  file.  Infor¬ 
mation  files  have  the  same  syntax.  Backslash  ‘V  '^sed  as  with  sft(l)  to  quote  syntactically 
significant  characters  or  to  insert  transparent  newlines  into  a  line.  When  either  a  question  or  its 
answer  is  empty,  quiz  will  refrain  from  asking  it. 

FILES 

/  usr/games/quiz.k/* 

BUGS 

The  construct  ‘a|ab’  doesn’t  work  in  an  information  file.  Use  ‘a{b}’. 
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NAME 

rain  —  animated  raindrops  display 

SYNOPSIS 

/usr/games/rain 

DESCRIPTION 

Rain’s  display  is  modeled  after  the  VAX/VMS  program  of  the  same  name.  The  terminal  has  to 
be  set  for  9600  baud  to  obtain  the  proper  effect. 

As  with  all  programs  that  use  termcap,  the  TERM  environment  variable  must  be  set  (and 
exported)  to  the  type  of  the  terminal  being  used. 

FILES 

/etc/termcap 
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NAME 

sail  —  multi-user  wooden  ships  and  iron  men 

SYNOPSIS 

sail  I  —X  I  {  num  j 

DESCRIPTION 

Sail  is  a  computer  version  of  Avalon  Hill’s  game  of  fighting  sail  originally  developed  by  S.  Craig 
Taylor. 

NOTES 

Sail  is  really  two  programs  in  one.  Each  player  keeps  track  of  his  own  ship  plus  a  DRIVER  pro¬ 
gram  is  execl’d  (by  the  first  player)  to  keep  track  of  the  computer’s  ships. 

The  player  is  given  the  first  available  ship  in  a  scenario  and  the  computer  takes  the  rest.  Obvi¬ 
ously  the  more  ships  in  your  game,  the  longer  the  DRIVER  will  take  to  move  them.  If  additional 
players  join  the  game,  they  will  be  given  ships  and  the  DRIVER  will  have  less  work  to  do. 

HISTORICAL  INFO 

Old  Square  Rigger’s  were  very  maneuverable  ships  capable  of  intricate  sailing.  Their  one  main 
disadvantage  was  being  unable  to  sail  very  close  to  the  wind.  The  design  of  wooden  ship  allowed 
only  for  the  guns  to  bear  to  the  left  and  right  sides.  A  few  guns  of  smj.ll  aspect  (usually  6  or  9 
pounders)  could  point  forward,  but  their  effect  would  be  small  compared  to  a  68  gun  broadside  of 
24  pounders.  The  guns  bear  approximately  like  so: 

\ 

b - 

—0 

\ 

\ 

\  up  to  a  range  of  ten  (for  round  shot) 

\ 

\ 

\ 
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An  interesting  phenomenon  occurred  when  a  broadside  could  Are  down  the  length  of  an  enemy 
ship.  The  shot  tended  to  bounce  along  the  deck  and  did  several  times  more  damage.  This 
phenomenon  was  called  a  rake.  It  happened  that  a  stern  rake  (firing  from  the  stern  to  the  bow) 
occasioned  more  damage  than  a  bow  rake,  so  that  was  the  most  desirable. 

\ 

b - 

—0 

\ 

\  Oa  —  Stern  rake! 

\ 

\ 

\ 

\ 

\ 

Most  ships  were  equipped  with  Carronades  which  were  very  large,  close  range  cannons.  The  car- 
ronades  have  a  range  of  two  in  this  game  and  can  considerably  add  to  your  fire-power  when  they 
come  to  bear.  If  the  distance  to  the  target  ship  is  greater  than  6,  the  guns  can  only  fire  at  the 
rigging.  A  ship’s  guns  could  fire  a  variety  of  ammunition.  For  example: 

ROUND 

Range  of  10.  Good  for  hull  or  rigging  hits. 

DOUBLE 

Range  of  1.  Extra  good  for  hull  or  rigging  hits.  Double  takes  two  turns  to  load. 

CHAIN 

Range  of  3.  Excellent  for  tearing  down  rigging.  Cannot  damage  hull  or  guns,  though. 

GRAPE 

Range  of  1.  Devastating  against  enemy  crews. 

When  a  ship  has  been  battered  into  a  hulk  (zero  hull),  it  has  no  choice  but  to  surrender  to  the 
firing  ship.  This  ceremony  is  called  'striking  your  colours.'  A  struck  ship  has  a  chance  of 
exploding  or  sinking  after  a  while.  When  a  ship  surrenders,  its  point  value  is  given  to  the  aggres¬ 
sor.  When  a  ship  is  captured,  twice  the  point  value  is  awarded  the  victor. 

Normally,  ships  sailed  into  battle  with  greatly  shortened  sail  to  avoid  excessive  damage  to  the 
precious  rigging.  However,  in  this  game  the  player  can  increase  to  full  sails  and  move  much  fas¬ 
ter  if  he  wishes.  But,  all  rigging  hits  incurred  with  full  sails  set  are  doubled.  The  direction  rose 
displayed  on  the  sample  screen  gives  the  maximum  speeds  possible  for  a  specific  ship  at  all  atti¬ 
tudes  to  the  wind.  The  full  sail  speeds  are  in  parenthesis. 

Repairs  can  be  made  at  the  slow  rate  of  two  (hull,  gun,  or  rigging)  hits  restored  per  three  turns. 

Ships  of  class  3  or  greater  drift  when  there  is  wind  at  the  rate  of  one  'square'  per  turn.  Ships  of 
the  Line  drift  one  'square'  every  other  turn. 

INSTRUCTIONS 

Sail  follows  the  Avalon  Hill  advanced  rules  very  closely  using  the  optional  rules  for  ’exploding 
ships’,  Tull  sails’,  and  some  others,  A  few  unique  commands  have  been  added  which  seemed  to 
be  helpful  on  the  reduced  screen,  ’i’  is  such  a  command. 

Boarding  had  to  go  through  a  major  revision.  To  prevent  immediate  capture  of  an  unprepared 
crew  (fouling  is  often  not  reported  until  after  boarding  has  commenced)  the  boarded  ship 
automatically  fights  defensively  (at  a  small  disadvantage)  if  no  DBF’s  have  been  prepared. 
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The  Order  of  Play  has  been  eliminated  for  the  player,  but  the  DRIVER  still  abides  by  it. 

The  commands  for  the  player  were  designed  to  be  as  intelligent  as  possible  to  save  typing.  Some 

of  the  nuances  I  developed  should  be  explained. 

Your  prompt 

The  others  I  will  illustrate  with  examples. 

moYe(3,  2):  rll  /♦  3  movements  max,  of  which  two 

may  be  45’  turns.  ♦/ 

move(3,’2):  Irl  /♦  3  movements  max  of  which  two  may 

be  45’  turns,  but  the  ship  must 
move  ahead  before  turning  (there 
is  a  loss  of  headway  after 
drifting)  */ 

moYe(0,’0):  r  /♦  You  can  always  make  one  turn 

even  when  you  can’t  move  straight 
ahead.  */ 

If  you  are  grappled,  fouled,  or  out  of  crew,  you  cannot  move  of  course. 
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COMMANDS 

T  Fire  broadsides  if  they  bear 
r  Reload 

’m’  Move  (see  above  &  below) 

4*  Ask  lookout  for  closest  ship 

Ask  lookout  for  closest  enemy  ship 
’s*  Send  a  message  around  the  fleet 
’b*  Attempt  to  board  an  enemy  ship 
’L*  Unload  broadsides  (to  change  ammo) 
’B’  Recall  boarding  parties 
V’  Change  set  of  sail 
V*  Repair 

*u*  Attempt  to  unfoul 
’g*  Grapple/ungrapple 
’"L’  Redraw  screen 
Quit 


SCENARIOS 
Ranger  vs*  Drake: 

Wind  from  the  N,  blowing  a  fresh  breeze. 


(a)  Ranger  19  gun  Sloop  (crack  crew)  (7  pts) 

(b)  Drake  17  gun  Sloop  (crack  crew)  (6  pts) 

The  Battle  of  Flamborough  Head: 

Wind  from  the  S,  blowing  a  fresh  breeze. 


This  IS  John  Paul  Jones*  first  famous  battle.  Aboard  the  Bonhomme  Richard,  he  was  able  to 
overcome  the  Serapis’s  greater  firepower  by  quickly  boarding  her. 


(a)  Bonhomme  Rich  42  gun  Corvette  (crack  crew)  (11  pts) 

(b)  Sefapis  44  gun  Frigate  (crack  crew)  (12  pts) 

Arbuthnot  and  Des  Touches: 

Wind  from  the  N,  blowing  a  gale. 


(b)  America 
(b)  Befford 
(b)  Adamant 
(b)  London 
(b)  Royal  Oak 
(f)  Neptune 
(f)  Due  Bougogne 
(f)  Conquerant 
(f)  Provence 
(f)  Romulus 


64  gun  Ship  of  the  Line  (crack  crew)  (20  pts) 

74  gun  Ship  of  the  Line  (crack  crew)  (26  pts) 

50  gun  Ship  of  the  Line  (crack  crew)  (17  pts) 
98  gun  3  Decker  SOL  (crack  crew)  (28  pts) 

74  gun  Ship  of  the  Line  (crack  crew)  (26  pts) 
74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 
80  gun  3  Decker  SOL  (average  crew)  (27  pts) 
74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 
64  gun  Ship  of  the  Line  (average  crew)  (18  pts) 
44  gun  Ship  of  the  Line  (average  crew)  (10  pts) 


Suifren  and  Hughes: 

Wind  from  the  S,  blowing  a  fresh  breeze. 


(b)  Monmouth 
(b)  Hero 
(b)  Isis 
(b)  Superb 
(b)  Burford 


74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 
74  gun  Ship  of  the  Line  (crack  crew)  (26  pts) 

50  gun  Ship  of  the  Line  (crack  crew)  (l7  pts) 

74  gun  Ship  of  the  Line  (crack  crew)  (27  pts) 

74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 
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(f)  Flamband  60  gun  Ship  of  the  Line  (average  crew)  (14  pts) 

(f)  Annibal  74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 

(f)  Severe  64  gun  Ship  of  the  Line  (average  crew)  (18  pts) 

(f)  Brilliant  80  gun  Ship  of  the  Line  (crack  crew)  (31  pts) 

(f)  Sphinx  80  gun  Ship  of  the  Line  (average  crew)  (27  pts) 

Nymphe  vs,  Cleopatra: 

Wind  from  the  S,  blowing  a  fresh  breeze. 


(b)  Nymphe  36  gun  Frigate  (crack  crew)  (11  pts) 

(f)  Cleopatre  36  gun  Frigate  (average  crew)  (10  pts) 

Mars  vs.  Hercule: 

Wind  from  the  S,  blowing  a  fresh  breeze. 

(b)  Mars  74  gun  Ship  of  the  Line  (crack  crew)  (26  pts) 

(f)  Hercule  74  gun  Ship  of  the  Line  (average  crew)  (23  pts) 

Ambuscade  vs.  Baionnaise: 

Wind  from  the  N,  blowing  a  fresh  breeze. 


(b)  Ambuscade  32  gun  Frigate  (average  crew)  (9  pts) 
(f)  Baionnaise  24  gun  Corvette  (average  crew)  (9  pts) 

Constellation  vs.  Insurgent: 

Wind  from  the  S,  blowing  a  gale. 

(a)  Constellation  38  gun  Corvette  (elite  crew)  (17  pts) 

(f)  Insurgent  36  gun  Corvette  (average  crew)  (11  pts) 

Constellation  vs.  Vengeance: 

Wind  from  the  S,  blowing  a  fresh  breeze. 


(a)  Constellation  38  gun  Corvette  (elite  crew)  (17  pts) 
(f)  Vengeance  40  gun  Frigate  (average  crew)  (16  pts) 


The  Battle  of  Lissa: 

Wind  from  the  S,  blowing  a  fresh  breeze. 


(b)  Amphion 
(b)  Active 
(b)  Volage 
(b)  Cerberus 
(f)  Favorite 
(f)  Flore 
(f)  Danae 
(f)  Bellona 
(f)  Corona 
(f)  Carolina 


32  gun  Frigate  (elite  crew)  (13  pts) 
38  gun  Frigate  (elite  crew)  (18  pts) 

22  gun  Frigate  (elite  crew)  (11  pts) 

32  gun  Frigate  (elite  crew)  (13  pts) 

40  gun  Frigate  (average  crew)  (15  pts) 
40  gun  Frigate  (average  crew)  (15  pts) 
40  gun  Frigate  (crack  crew)  (17  pts) 

32  gun  Frigate  (green  crew)  (9  pts) 

40  gun  Frigate  (green  crew)  (12  pts) 
32  gun  Frigate  (green  crew)  (7  pts) 


Constitution  vs.  Guerriere: 

Wind  from  the  SW,  blowing  a  gale. 


(a)  Constitution  44  gun  Corvette  (elite  crew)  (24  pts) 

(b)  Guerriere  38  gun  Frigate  (crack  crew)  (15  pts) 

United  States  vs.  Macedonian: 

Wind  from  the  S,  blowing  a  fresh  breeze. 
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(a)  United  States  44  gun  Frigate  (elite  crew)  (24  pts) 

(b)  Macedonian  38  gun  Frigate  (crack  crew)  (16  pts) 

Constitution  vs.  Java: 

Wind  from  the  S,  blowing  a  fresh  breeze. 

(a)  Constitution  44  gun  Corvette  (elite  crew)  (24  pts) 

(b)  Java  38  gun  Corvette  (crack  crew)  (19  pts) 

Chesapeake  vs.  Shannon: 

Wind  from  the  S,  blowing  a  fresh  breeze. 


(a)  Chesapeake  38  gun  Frigate  (average  crew)  (14  pts) 

(b)  Shannon  38  gun  Frigate  (elite  crew)  (17  pts) 

The  Battle  of  Lake  Erie: 

Wind  from  the  S,  blowing  a  light  breeze, 

(a)  Lawrence  20  gun  Sloop  (crack  crew)  (9  pts) 

(a)  Niagara  20  gun  Sloop  (elite  crew)  (12  pts) 

(b)  Lady  Prevost  13  gun  Brig  (crack  crew)  (5  pts) 

(b)  Detroit  19  gun  Sloop  (crack  crew)  (7  pts) 

(b)  Q.  Charlotte  17  gun  Sloop  (crack  crew)  (6  pts) 

Wasp  vs.  Reindeer: 

Wind  from  the  S,  blowing  a  light  breeze. 

(a)  Wasp  20  gun  Sloop  (elite  crew)  (12  pts) 

(b)  Reindeer  18  gun  Sloop  (elite  crew)  (9  pts) 

Constitution  vs.  Cyane  and  Levant: 

Wind  from  the  S,  blowing  a  moderate  breeze. 

(a)  Constitution  44  gun  Corvette  (elite  crew)  (24  pts) 

(b)  Cyane  24  gun  Sloop  (crack  crew)  (11  pts) 

(b)  Levant  20  gun  Sloop  (crack  crew)  (10  pts) 

Pellew  vs.  Droits  de  L’Homme: 

Wind  from  the  N,  blowing  a  gale. 

(b)  Indefatigable  44  gun  Frigate  (elite  crew)  (14  pts) 

(b)  Amazon  36  gun  Frigate  (crack  crew)  (14  pts) 

(f)  Droits  L’Hom  74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 

Algeciras: 

Wind  from  the  SW,  blowing  a  moderate  breeze. 


(b)  Caesar  80  gun  Ship  of  the  Line  (crack  crew)  (31  pts) 

(b)  Pompee  74  gun  Ship  of  the  Line  (crack  crew)  (27  pts) 

(b)  Spencer  74  gun  Ship  of  the  Line  (crack  crew)  (25  pts) 

(b)  Hannibal  98  gun  3  Decker  SOL  (crack  crew)  (28  pts) 

(s)  Real-Carlos  112  gun  3  Decker  SOL  (green  crew)  (27  pts) 

(s)  San  Fernando  96  gun  3  Decker  SOL  (green  crew)  (24  pts) 

(s)  Argonauta  80  gun  Ship  of  the  Line  (green  crew)  (23  pts) 

(s)  San  Augustine  74  gun  Ship  of  the  Line  (green  crew)  (20  pts) 
(f)  Indomptable  80  gun  Ship  of  the  Line  (average  crew)  (27  pts) 
(f)  Desaix  74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 
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Lake  Champlain: 

Wind  from  the  N,  blowing  a  fresh  breeze. 

(a)  Saratoga  26  gun  Sloop  (crack  crew)  (12  pts) 

(a)  Eagle  20  gun  Sloop  (crack  crew)  (11  pts) 

(a)  Ticonderoga  17  gun  Sloop  (crack  crew)  (0  pts) 

(a)  Preble  7  gun  Brig  (crack  crew)  (4  pts) 

(b)  Confiance  37  gun  Frigate  (crack  crew)  (14  pts) 

(b)  Linnet  16  gun  Sloop  (elite  crew)  (10  pts) 

(b)  Chubb  11  gun  Brig  (crack  crew)  (5  pts) 

Last  Voyage  of  the  USS  President: 

Wind  from  the  N,  blowing  a  fresh  breeze. 

(a)  President  44  gun  Frigate  (elite  crew)  (24  pts) 

(b)  Endymion  40  gun  Frigate  (crack  crew)  (17  pts) 

(b)  Pomone  44  gun  Frigate  (crack  crew)  (20  pts) 

(b)  Tenedos  38  gun  Frigate  (crack  crew)  (15  pts) 

Hornblower  and  the  Natividad: 

Wind  from  the  E,  blowing  a  gale. 

A  scenario  for  you  Horny  fans.  Remember,  he  sank  the  Natividad  against  heavy  odds  and  winds. 
Hint:  don*t  try  to  board  the  Natividad,  her  crew  is  much  bigger,  albeit  green, 

(b)  Lydia  36  gun  Frigate  (elite  crew)  (13  pts) 

(s)  Natividad  50  gun  Ship  of  the  Line  (green  crew)  (14  pts) 

Curse  of  the  Flying  Dutchman: 

Wind  from  the  S,  blowing  a  fresh  breeze. 

Just  for  fun,  take  the  Piece  of  cake. 

(s)  Piece  of  Cake  24  gun  Corvette  (average  crew)  (9  pts) 

(f)  Flying  Dutchy  120  gun  3  Decker  SOL  (elite  crew)  (43  pts) 

The  South  Pacific; 

Wind  from  the  S,  blowing  a  strong  breeze. 

(a)  USS  Scurvy  136  gun  3  Decker  SOL  (mutinous  crew)  (27  pts) 

(b)  HMS  Tahiti  120  gun  3  Decker  SOL  (elite  crew)  (43  pts) 

(s)  Australian  32  gun  Frigate  (average  crew)  (9  pts) 

(f)  Bikini  Atoll  7  gun  Brig  (crack  crew)  (4  pts) 

Hornblower  and  the  battle  of  Rosas 

Wind  from  the  E,  blowing  a  fresh  breeze. 

The  only  battle  Hornblower  ever  lost.  He  was  able  to  dismast  one 
ship  and  stern  rake  another's  though.  See  if  you  can  do  as  well. 

(b)  Sutherland  74  gun  Ship  of  the  Line  (crack  crew)  (26  pts) 

(f)  Turenne  80  gun  3  Decker  SOL  (average  crew)  (27  pts) 

(f)  Nightmare  74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 

(f)  Paris  112  gun  3  Decker  SOL  (green  crew)  (27  pts) 

(f)  Napolean  74  gun  Ship  of  the  Line  (green  crew)  (20  pts) 
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Cape  Horn: 

Wind  from  the  NE,  blowing  a  strong  breeze. 


(a)  Concord 

(a)  Berkeley 

(b)  Thames 
(s)  Madrid 
(f)  Musket 


80  gun  Ship  of  the  Line  (average  crew)  (27  pis) 
98  gun  3  Decker  SOL  (crack  crew)  (28  pts) 

120  gun  3  Decker  SOL  (elite  crew)  (43  pts) 

112  gun  3  Decker  SOL  (green  crew)  (27  pts) 

80  gun  3  Decker  SOL  (average  crew)  (27  pts) 


New  Orleans: 

Wind  from  the  SE,  blowing  a  fresh  breeze. 


Watch  that  little  Cypress  go! 

(a)  Alligator  120  gun  3  Decker  SOL  (elite  crew)  (43  pts) 

(b)  Firefly  74  gun  Ship  of  the  Line  (crack  crew)  (27  pts) 

(b)  Cypress  44  gun  Frigate  (elite  crew)  (14  pts) 

Botany  Bay: 

Wind  from  the  N,  blowing  a  fresh  breeze. 


(b)  Shark  64  gun  Ship  of  the  Line  (average  crew)  (18  pts) 

(f)  Coral  Snake  44  gun  Corvette  (elite  crew)  (24  pts) 

(f)  Sea  Lion  44  gun  Frigate  (elite  crew)  (24  pts) 

Voyage  to  the  Bottom  of  the 

Wind  from  the  NW,  blowing  a  fresh  breeze. 


This  one  is  dedicated  to  David  Hedison. 


(a)  Seaview  120  gun  3  Decker  SOL  (elite  crew)  (43  pts) 

(a)  Flying  Sub  40  gun  Frigate  (crack  crew)  (17  pts) 

(b)  Mermaid  136  gun  3  Decker  SOL  (mutinous  crew)  (27  pts) 

(s)  Giant  Squid  112  gun  3  Decker  SOL  (green  crew)  (27  pts) 

Frigate  Action: 

Wind  from  the  E,  blowing  a  fresh  breeze. 


(a)  Killdeer  40  gun  Frigate  (average  crew)  (15  pts) 

(b)  Sandpiper  40  gun  Frigate  (average  crew)  (15  pts) 

(s)  Curlew  38  gun  Frigate  (crack  crew)  (16  pts) 


The  Battle  of  Midway: 

Wind  from  the  E,  blowing  a  moderate  breeze. 


(a)  Enterprise 
(a)  Yorktown 
(a)  Hornet 
(f)  Akagi 
(f)  Kaga 
(f)  Soryu 


80  gun  Ship  of  the  Line  (crack  crew)  (31  pts) 

80  gun  Ship  of  the  Line  (average  crew)  (27  pts) 
74  gun  Ship  of  the  Line  (average  crew)  (24  pts) 
112  gun  3  Decker  SOL  (green  crew)  (27  pts) 

96  gun  3  Decker  SOL  (green  crew)  (24  pts) 

80  gun  Ship  of  the  Line  (green  crew)  (23  pts) 


EXAMPLE  OF  MOVE: 

/  Max  distance  (including  turns) 

/  Max  number  of  45  degree  turns  (one  at  a  time  only) 

/  / 

Move(3,  2):  rll  /*  move  right,  ahead,  left 
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♦ 

* 

* 

*' 

♦ 

* 


0  START 
b 


bO  RIGHT 


* 

* 


bO 

ONE 

0 

b 

LEFT 

SAMPLE  GAME: 

tutorial%  sail 
Choose  a  scenario: 


NUMBER  SHIPS 


0) 

1) 

2) 

3) 

4) 

5) : 

6) 

7) 

8) 
Q) 
10) 
11) 
12) 

13) 

14) 

15) 

16) 

17) 

18) 

19) 

20) 
21) 
22) 

23) 

24) 

25) 

26) 

27) 

28) 

29) 

30) 


2 

2 

10 

10 

2 

2 

2 

2 

2 

10 

2 

2 

2 

2 

5 

2 

3 

3 
10 
7 

4 
2 
2 

4 

5 

5 
3 

3 

4 
3 

6 


IN  PLAY  TITLE 

no  Ranger  vs.  Drake 

no  The  Battle  of  Flamborough  Head 

no  Arbuthnot  and  Des  Touches 

no  Suffren  and  Hughes 

no  Nymphe  vs.  Cleopatre 

no  Mars  vs.  Hercule 

no  Ambuscade  vs.  Baionnaise 

no  Constellation  vs.  Insurgent 

no  Constellation  vs.  Vengeance 

no  The  Battle  of  Lissa 

no  Constitution  vs.  Guerriere 

no  United  States  vs.  Macedonian 

no  Constitution  vs.  Java 

no  Chesapeake  vs.  Shannon 

no  The  Battle  of  Lake  Erie 

no  Wasp  vs.  Reindeer 

no  Constitution  vs.  Cyane  and  Levant 

no  Pellew  vs.  Droits  de  L’Homme 

no  Algeciras 

no  Lake  Champlain 

no  Last  Voyage  of  the  USS  President 

no  Hornblower  and  the  Natividad 

no  Curse  of  the  Flying  Dutchman 

no  The  South  Pacific 

no  Hornblower  and  the  battle  of  Rosas  bay 

no  Cape  Horn 

no  New  Orleans 

no  Botany  Bay 

no  Voyage  to  the  Bottom  of  the  Sea 

no  Frigate  Action 

no  The  Battle  of  Midway 


Scenario  number?  21 
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Your  ship  is  the  Lydia,  a  36  gun  Frigate  (elite  crew). 
Your  name,  Captain?  Dave  #1 

Initial  broadside  left  (grape,  chain,  round,  double):  d 


Initial  broadside  right  (grape,  chain,  round,  double):  r 

Class  3  (36  guns)  Frigate  ’Lydia*  (bO)  Points:  0  Fouls:  0  Grapples:  0 


1 


"0  —  a  sinking  ship 

0 

b  #1  -  an  exploding  ship 


bow  of  Lydia 


!  —  a  struck  ship  SO 


j  wind  speed  -5+ 
j  and  direction 

I  (blowing  from  right) 
r _ 

t 

\ 

stern  of  Natividad 
Natividad  has  full  sails  set. 


Aye  aye.  Sir 


Turn  0 


load:  port  and  starboard  —  Load  D!  R!  0  1(1) 


crew:  3  sections - 

Hull  9 

Crew  4  42 

\!/ 

1(1) 

guns:  port  and  starboard  — 

Guns  4  4 

A 

1 

1 

e 

carronades:  port  and  starboard  - 

Carr  2  2 

3(5) 

rigging  4  masts - 

Rigg  5  5  5  5 

2(4) 
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NAME 

snake,  snscore  —  display  chase  game 
SYNOPSIS 

/usr/gameB/snake  [  — w»  ]  [  —In  ] 

/usr /games  /snscore 

DESCRIPTION 

Snake  is  a  display-based  game  which  must  be  played  on  a  CRT  terminal  from  among  those  sup¬ 
ported  by  vi(l).  The  object  of  the  game  is  to  make  as  much  money  as  possible  without  getting 
eaten  by  the  snake.  The  —1  and  — w  options  allow  you  to  specify  the  length  and  width  of  the 
field.  By  default  the  entire  screen  (except  for  the  last  column)  is  used. 

You  are  represented  on  the  screen  by  an  I.  The  snake  is  6  squares  long  and  is  represented  by  S's. 
The  money  is  $,  and  an  exit  is  #.  Your  score  is  posted  in  the  upper  left  hand  corner. 

You  can  move  around  using  the  same  conventions  as  vi(l),  the  h,  j,  k,  and  1  keys  work,  as  do  the 
arrow  keys.  Other  possibilities  include: 

sefc  These  keys  are  like  hjkl  but  form  a  directed  pad  around  the  d  key. 

HJKL  These  keys  move  you  all  the  way  in  the  indicated  direction  to  the  same  row  or  column  as 
the  money.  This  does  not  let  you  jump  away  from  the  snake,  but  rather  saves  you  from 
having  to  type  a  key  repeatedly.  The  snake  still  gets  all  his  turns. 

SEFC  Likewise  for  the  upper  case  versions  on  the  left. 

ATPB  These  keys  move  you  to  the  four  edges  of  the  screen.  Their  position  on  the  keyboard  is 
the  mnemonic,  e.g.  P  is  at  the  far  right  of  the  keyboard. 

X  This  lets  you  quit  the  game  at  any  time. 

p  Points  in  a  direction  you  might  want  to  go. 

w  Space  warp  to  get  out  of  tight  squeezes,  at  a  price. 

!  Shell  escape 

*Z  Suspend  the  snake  game,  on  systems  which  support  it.  Otherwise  an  interactive  shell  is 
started  up. 

To  earn  money,  move  to  the  same  square  the  money  is  on.  A  new  $  will  appear  when  you  earn 
the  current  one.  As  you  get  richer,  the  snake  gets  hungrier.  To  leave  the  game,  move  to  the 
exit  (#). 

A  record  is  kept  of  the  personal  best  score  of  each  player.  Scores  are  only  counted  if  you  leave  at 
the  exit,  getting  eaten  by  the  snake  is  worth  nothing. 

As  in  pinball,  matching  the  last  digit  of  your  score  to  the  number  which  appears  after  the  game 
is  worth  a  bonus. 

To  see  who  wastes  time  playing  snake,  run  (uer/ games/ snscore  . 

FILES 

/usr/games/lib/snakerawscores  database  of  personal  bests 
/usr/games/lib/snake.log  log  of  games  played 

BUGS 

When  playing  on  a  small  screen,  it’s  hard  to  tell  when  you  hit  the  edge  of  the  screen. 

The  scoring  function  takes  into  account  the  size  of  the  screen.  A  perfect  function  to  do  this 
equitably  has  not  been  devised. 
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NAME 

trek  —  trekkie  game 


SYNOPSIS 

/uBr/games/trek  [  [  — a  j  file  ] 

DESCRIPTION 

Trek  is  a  game  of  space  glory  and  war.  Below  is  a  summary  of  commands.  For  complete  docu¬ 
mentation,  see  Trek  by  Eric  Allman. 

If  a  filename  is  given,  a  log  of  the  game  is  written  onto  that  file.  If  the  —a  flag  is  given  before 
the  filename,  that  file  is  appended  to,  not  truncated. 

The  game  will  ask  you  what  length  game  you  would  like.  Valid  responses  are  “short'\ 
“medium"’,  and  “long”.  You  may  also  type  “restart”,  which  restarts  a  previously  saved  game. 
You  will  then  be  prompted  for  the  skill,  to  which  you  must  respond  “novice”,  “fair”,  “good”, 
“expert”,  “commadore”,  or  “impossible”.  You  should  normally  start  out  with  a  novice  and  work 
up. 


In  general,  throughout  the  game,  if  you  forget  what  is  appropriate  the  game  will  tell  you  what  it 
expects  if  you  just  type  in  a  question  mark. 


COMMAND  SUMMARY 
abandon 
cloak  up/down 
computer  request;  ... 
destruct 
help 
Irscan 

phasers  automatic  amount 
phasers  manual  amtl  coursel  spreadl  ... 
torpedo  course  [yesj  angle/no 
ram  course  distance 

shell 

srscan  [yes/nol 

status 

undock 

warp  warp^factor 


capture 

damages 

dock 

Impulse  course  distance 
move  course  distance 


rest  time 
shields  up/down 

terminate  yes/no 

visual  course 
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NAME 

worm  —  Play  the  growing  worm  game 
SYNOPSIS 

/usr/gameB/worm  [  size  ] 

DESCRIPTION 

In  worm,  you  are  a  little  worm,  your  body  is  the  V’s  on  the  screen  and  your  head  is  the 
You  move  with  the  hjkl  keys  (as  in  the  game  snake).  If  you  don’t  press  any  keys,  you  continue  in 
the  direction  you  last  moved.  The  upper  case  HJKL  keys  move  you  as  if  you  had  pressed  several 
(9  for  HL  and  5  for  JK)  of  the  corresponding  lower  case  key  (unless  you  run  into  a  digit,  then  it 
stops). 

On  the  screen  you  will  see  a  digit,  if  your  worm  eats  the  digit  is  will  grow  longer,  the  actual 
amount  longer  depends  on  which  digit  it  was  that  you  ate.  The  object  of  the  game  is  to  see  how 
long  you  can  make  the  worm  grow. 

The  game  ends  when  the  worm  runs  into  either  the  sides  of  the  screen,  or  itself.  The  current 
score  (how  much  the  worm  has  grown)  is  kept  in  the  upper  left  corner  of  the  screen. 

The  optional  argument,  if  present,  is  the  initial  length  of  the  worm. 

BUGS 

If  the  initial  length  of  the  worm  is  set  to  less  than  one  or  more  than  7S,  various  strange  things 
happen. 
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NAME 

worms  —  animate  worms  on  a  display  terminal 
SYNOPSIS 

/u8r /games/ worms  [  “*fleld  ]  [  —length  #  \  [  —number  #  ]  [  —trail  | 

DESCRIPTION 

Brian  Horn  (cithepibdh)  showed  me  a  TOPS-20  program  on  the  DEC-2136  machine  called 
WORM^  and  suggested  that  I  write  a  similar  program  that  would  run  under  Unix,  I  did,  and  no 
apologies. 

—field  makes  a  "field”  for  the  worm(s)  to  cat;  -trail  causes  each  worm  to  leave  a  trail  behind  it. 
You  can  figure  out  the  rest  by  yourself. 

FILES 

/etc/termcap 

SEE  ALSO 

Snails,  by  Karl  Heuer 

BUGS 

The  lower-right-hand  character  position  will  not  be  updated  properly  on  a  terminal  that  wraps  at 
the  right  margin. 

Terminal  initialization  is  not  performed. 
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NAME 

wump  -  the  game  of  hunt-the-wumpus 


SYNOPSIS 

/uar/games/wump 

DESCRIPTION 

Wump  plays  the  game  of  ‘Hunt  the  Wumpus.’  A  Wumpus  is  a  creature  that  lives  in  a  cave  with 
several  rooms  connected  by  tunnels.  You  wander  among  the  rooms,  trying  to  shoot  the  Wumpus 
with  an  arrow,  meanwhile  avoiding  being  eaten  by  the  Wumpus  and  falling  into  Bottomless  Pits. 
There  are  also  Super  Bats  which  are  likely  to  pick  you  up  and  drop  you  in  some  random  room. 

The  program  asks  various  questions  which  you  answer  one  per  line;  it  will  give  a  more  detailed 
description  if  you  want. 

This  program  is  based  on  one  described  in  People’s  Computer  Company,  S,  2  (November  1973). 
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NAME 

miscellaneous  —  miscellaneous  useful  information  pages 
DESCRIPTION 

This  section  contains  miscellaneous  documentation,  mostly  in  the  area  of  text  processing  macro 
packages  for 


ascii 

map  of  ASCII  character  set 

eqnchar 

special  character  definitions  for  eqn 

hier 

file  system  hierarchy 

mailaddr 

mail  addressing  description 

man 

macros  to  typeset  manual  pages 

me 

macros  for  formatting  papers 

ms 

macros  for  formatting  manuscripts 
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NAME 

ascii  —  map  of  ASCII  character  set 

SYNOPSIS 

cat  /uar/pub/aacll 

DESCRIPTION 

Ascii  is  a  map  of  the  ASCII  character  set,  to  be  printed  as  needed.  It  contains: 


;ooo 

nul 

|001 

soh 

[002 

stx 

[003 

etx 

[004 

eot 

[005 

enq 

[006 

ack 

o 

o 

be!  1 

joio 

bs 

|011 

ht 

[012 

nl 

[013 

vt 

[014 

np 

[015 

cr 

[016 

so 

[017 

si  1 

|020 

die 

|02I 

del 

[022 

de2 

[023 

dc3 

[024 

dc4 

[025 

nak 

[026 

syn 

[027 

etb[ 

j030 

can 

[031 

em 

[032 

sub 

[033 

esc 

[034 

f  s 

[035 

gs 

[036 

rs 

[037 

us  [ 

]040 

sp 

|041 

f 

[042 

tf 

[043 

# 

[044 

$ 

[045 

% 

[046 

& 

[047 

y  1 

j050 

( 

|051 

) 

[052 

[053 

+ 

[054 

f 

[055 

- 

[056 

. 

[057 

/  i 

i060 

0 

j061 

1 

[062 

2 

[063 

3 

[064 

4 

[065 

5 

[066 

5 

[067 

7  [ 

|070 

8 

!071 

9 

[072 

: 

[073 

f 

[074 

< 

[075 

= 

[076 

> 

[077 

?  [ 

|100 

@ 

[101 

A 

[102 

B 

[103 

C 

[104 

D 

[105 

E 

[106 

F 

[107 

G  1 

|1I0 

H 

[111 

I 

[112 

J 

[113 

K 

[114 

L 

[115 

M 

[116 

N 

[117 

O  [ 

!120 

P 

[121 

Q 

[122 

R 

[123 

S 

[124 

T 

[125 

U 

[126 

V 

[127 

W  [ 

|130 

X 

[131 

Y 

[132 

Z 

[133 

i 

[134 

\ 

[135 

] 

[136 

[137 

_  1 

jl40 

\ 

[141 

a 

[142 

b 

[143 

c 

[144 

d 

[145 

e 

[146 

f 

[147 

g  ! 

jl50 

h 

[151 

i 

[152 

j 

[153 

k 

[154 

1 

[155 

m 

[156 

n 

[157 

o  j 

|160 

P 

[161 

q 

[162 

r 

[163 

s 

[164 

t 

[165 

u 

[166 

V 

[167 

w  { 

jl70 

X 

[171 

y 

[172 

z 

[173 

{ 

[174 

! 

[175 

} 

[176 

[177 

del  1 

1  00 

nul 

!  01 

soh 

[  02 

stx 

[  03 

etx 

[  04 

eot 

[  05 

enq 

1  06 

ack 

[  07 

bel  1 

1  08 

bs 

[  09 

ht 

[  Oa 

nl 

j  Ob 

vt 

[  Oc 

np 

[  Od 

cr 

1  Oe 

so 

[  Of 

si  1 

!  10 

die 

1  11 

del 

1  12 

dc2 

1  18 

dc3 

!  14 

dc4 

!  18 

nak 

[  16 

syn 

1  17 

etb  [ 

!  18 

can 

!  19 

em 

[  la 

sub 

[  lb 

esc 

!  1*^ 

fs 

!  i<i 

gs 

[  le 

rs 

!  If 

us  j 

1  20 

sp 

i  21 

! 

1  22 

t* 

1  23 

# 

!  24 

$ 

[  25 

% 

1  26 

& 

[  27 

^  1 

[  28 

( 

[  29 

) 

[  2a 

♦ 

[  2b 

+ 

[  2c 

J 

[  2d 

- 

1  2e 

!  2f 

/  ! 

[  30 

0 

1  81 

1 

[  32 

2 

[  33 

3 

!  84 

4 

[  35 

5 

[  36 

6 

1  37 

7  1 

1  38 

8 

[  39 

9 

[  3a 

: 

[  3b 

t 

1  3c 

< 

1  3d 

= 

1  3e 

> 

1  3f 

?  j 

1  40 

@ 

1  'll 

A 

[  42 

B 

1  48 

C 

[  44 

D 

i  45 

E 

1  46 

F 

1  47 

G  ! 

1  ^8 

H 

[  49 

I 

[  4a 

J 

1  4b 

K 

1  4c 

L 

[  4d 

M 

I  4e 

N 

1  4f 

O  1 

1  50 

P 

!  81 

Q 

1  52 

R 

1  53 

S 

1  54 

T 

[  55 

U 

[  56 

V 

I  57 

W  [ 

j  58 

X 

1  59 

Y 

[  5a 

Z 

[  5b 

[ 

[  5c 

\ 

[  5d 

1 

[  5e 

!  8f 

^  1 

;  60 

!  01 

a 

1  62 

b 

[  63 

c 

[  64 

d 

[  65 

e 

[  66 

f 

1  67 

g  1 

1  68 

h 

[  69 

i 

[  6a 

j 

[  6b 

k 

[  6c 

1 

[  6d 

m 

[  6e 

n 

!  6f 

0  j 

j  70 

P 

1  71 

q 

{  72 

r 

[  73 

s 

!  74 

t 

1  75 

u 

1  76 

V 

[  77 

W  j 

j  78 

X 

[  79 

y 

[  7a 

z 

1  7b 

{ 

1  7c 

1 

1 

1  7d 

} 

I  7e 

[  7f 

del  1 

FILES 

/usr/pub/ascii 
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NAME 

eqnchar  “  special  character  definitions  for  eqn 
SYNOPSIS 

eqn  /usr/pub/eqnchar  [  files  ]  |  troff  |  options  ] 
neqn  /usr/pub/eqnchar  [  files  |  |  nr  off  |  options  | 

DESCRIPTION 

Eqnchar  contains  troff  and  nroff  character  definitions  for  constructing  characters  that  are  not 
available  on  the  Graphic  Systems  typesetter.  These  definitions  are  primarily  intended  for  use 
with  eqn  and  neqn.  It  contains  definitions  for  the  following  characters 


ctplus 

II 

11 

II 

square 

□ 

citimes 

(8) 

tangle 

( 

circle 

0 

wig 

rangle 

) 

blot 

□ 

-wig 

kbar 

k 

bullet 

• 

>mg 

ppd 

1 

prop 

« 

<wig 

<■> 

empty 

0 

=wig 

<=> 

member 

e 

star 

* 

!< 

<1: 

nomem 

big  star 

1> 

cup 

u 

=dot 

= 

ang 

4 

cap 

n 

or  sign 

V 

rang 

L 

in  cl 

n 

andsign 

A 

Sdot 

subset 

c 

^del 

_A 

ihf 

supset 

D 

oppA 

V 

quarter 

% 

!subset 

C 

oppE 

3 

Squarier 

% 

fsupsei 

D 

angstrom 

A 

degree 

• 

FILES 

/usr/pub/eqnchar 

SEE  ALSO 

troff(l),  eqn(l) 
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NAME 

hier  —  file  system  hierarchy 
DESCRIPTION 

The  following  outline  gives  a  quick  tour  through  a  representative  directory  hierarchy. 

/  root 
/v  mu  nix 

the  kernel  binary  (UNIX  itself) 

/lost-f  found 

directory  for  connecting  detached  files  for  f$ck{S) 

/dev/  devices,  see  section  4 

console  main  console,  tty{i) 
tty*  terminals,  Uy{i) 

xy*  disks,  xy(4S) 

rxy*  raw  disks,  a?|/(4S) 

« • « 

/bin/  utility  programs,  cf  /usr/bin/  (described  in  sect.  1) 
as  assembler 

cc  C  compiler  executive,  cf  /lib/ccom,  /lib/cpp,  /lib/c2 

csh  C  shell 

» « • 

/lib/  object  libraries  and  other  stuff,  cf  /usr/lib/ 

libc.a  system  calls,  standard  I/O,  etc.  (described  in  sect.  2,  3,  3S,  3C,  3N) 

•  •  • 

ccom  C  compiler  proper 

cpp  C  preprocessor 

c2  C  code  improver 

•  •  • 

/etc/  essential  data  and  maintenance  utilities;  described  in  section  8 
dump  dump  program  rfttmp(8) 
passwd  password  file,  passtt;d{5) 
group  group  file,  group{b) 
motd  message  of  the  day,  /o^m(l) 
termcap 

description  of  terminal  capabilities,  termcap{S) 
ttytype  table  of  what  kind  of  terminal  is  on  each  port,  ttytype{b) 
mtab  mounted  file  table,  m^a6(5) 
dumpdates 

dump  history,  dump (8) 

fstab  file  system  configuration  table  /?^o6(5) 

ttys  properties  of  terminals,  ^^ps(5) 

getty  part  of  logins  getty{Z) 

init  the  parent  of  all  processes,  init{S) 

rc  shell  script  to  bring  the  system  up 

cron  the  clock  daemon,  cron{S) 
mount  moun^(8) 

wall  u;uff(l) 

•  •  • 

/tmp/  temporary  files,  cf  /usr/tmp/ 
e*  used  by  cd(l) 

ctm*  used  by  ec(l) 

•  •  • 

/usr/  general-pupose  directory,  usually  a  mounted  file  system 
adm/  administrative  information 


460 


Last  change:  1  February  1985 


Sun  Release  2.0 


HIER(7) 


TABLES 


HIER(7) 


wtmp  login  history,  u^mp(5) 
messages 

hardware  error  messages 
bin/  utility  programs,  to  keep  /bin/  small 
etc/  administrative  programs,  to  keep  /etc/  small 
tmp/  temporaries,  to  keep  /tmp/  small 
stm*  used  by  ^or/(l) 
diet/  word  lists,  etc. 

words  principal  word  list,  used  by  /ooA;(l) 
spellhist 

history  file  for  apeW(l) 

games/ 

hangman 

lib/  library  of  stuff  for  the  games 
quiz.k/  what  g«t>(6)  knows 

index  category  index 
africa  countries  and  capitals 


include/ 

standard  #include  files 
a.out.h  object  file  layout, 
stdio.h  standard  I/O,  5Mto(3S) 
math.h  (3M) 

•  •  • 

sys/  system-defined  layouts,  cf  /sys/h 
lib/  object  libraries  and  stuff,  to  keep  /lib/  small 
atrun  scheduler  for  a^(l) 
lint/  utility  files  for  lint 

lint[l2j  subprocesses  for  (int{l) 

llib-lc  dummy  declarations  for  /lib/libc.a,  used  by  fini(l) 
llib-lm  dummy  declarations  for  /lib/libc.m 

•  •  • 

struct/  passes  of  a(r«cf(l) 

•  •  * 

tmac/  macros  for  troff{l) 
tmac.an 

macros  for  man  (7) 
tmac.s  macros  for  ms(7) 

•  • « 

font/  fonts  for  troff{l) 

ftR  Times  Roman 

ftB  Times  Bold 

•  •  • 

uucp/  programs  and  data  for  «ticp(lC) 

L.sys  remote  system  names  and  numbers 
uucico  the  real  copy  program 

•  •  • 

units  conversion  tables  for  unt7s(l) 

eign  list  of  English  words  to  be  ignored  by  ptx{l) 
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/usr/ 

man/  Pages  for  major  manuals  —  User^s  Guide  to  CommandOj  UNIX  Programmer's 
Manual,  and  System  Manager's  Guide,  man(l) 
manO/  general 

intro  introduction  to  Sun  System  Manuals,  in  ms{7)  format 
XX  template  for  manual  page 
manl/  chapter  1 
as.l 

spline.lg 


catl/  preformatted  pages  for  section  1 

■  •  • 

preserve/ 

editor  temporaries  preserved  here  after  crashes/hangups 
spool/  delayed  execution  files 
at/  used  by  (i/(l) 

Ipd/  used  by  /pr(l) 

lock  present  when  line  printer  is  active 
cf*  copy  of  file  to  be  printed,  if  necessary 
df*  daemon  control  file,  /pd(8) 
tf*  transient  control  file,  while  Ipr  is  working 
uucp/  work  files  and  staging  area  for  u«cp(lC) 

LOGFILE 

summary  log 

LOG.+  log  file  for  one  transaction 

mail/  mailboxes  for  ma:7(l) 

name  mail  file  for  user  name 
nome.lock 

lock  file  while  name  is  receiving  mail 

secretmail/ 

like  mail/ 

wd  initial  working  directory  of  a  user,  typically  wd  is  the  user’s  login  name 
•profile  set  environment  for  ^A(l),  env*ron(5) 

•cshrc  startup  file  for  csh{l) 

•exrc  startup  file  for  eaj(l) 

•mailrc  startup  file  for  matV(l) 
calendar 

user’s  datebook  for  catendar{l) 

ucb/  binaries  of  programs  developed  at  University  of  California  at  Berkeley, 

♦  •  • 

edit  editor  for  beginners 

ex  command  editor  for  experienced  users 

•  •  • 

mail  mail  rcading/sending  subsystem 
man  on  line  documentation 

•  •  • 

pi  Pascal  translator 

px  Pascal  interpreter 

•  •  • 

vi  visual  editor 
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SEE  ALSO 

ls(l),  whatis(l),  whereis(l),  which  (1),  ncheck(8),  iind(l),  grep(l) 

BUGS 

The  position  of  files  is  subject  to  change  without  notice. 
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NAME 

mailaddr  —  mail  addressing  description 
DESCRIPTION 

Mail  addresses  are  based  on  the  ARPANET  protocols  listed  at  the  end  of  this  manual  page. 
These  addresses  are  in  the  general  format 

user@domain 

where  a  domain  is  a  hierarchical  dot  separated  list  of  subdomains.  For  example,  the  address 
eric@monet,Berkeley.ARPA 

is  normally  interpreted  from  right  to  left:  the  message  should  go  to  the  ARPA  name  tables 
(which  do  not  correspond  exactly  to  the  physical  ARPANET),  then  to  the  Berkeley  gateway, 
after  which  it  should  go  to  the  local  host  monet.  When  the  message  reaches  monet  it  is  delivered 
to  the  user  “eric'*. 

Unlike  some  other  forms  of  addressing,  this  does  not  imply  any  routing.  Thus,  although  this 
address  is  specified  as  an  ARPA  address,  it  might  travel  by  an  alternate  route  if  that  was  more 
convenient  or  efficient.  For  example,  at  Berkeley  the  associated  message  would  probably  go 
directly  to  monet  over  the  Ethernet  rather  than  going  via  the  Berkeley  ARPANET  gateway. 

Abbreviation.  Under  certain  circumstances  it  may  not  be  necessary  to  type  the  entire  domain 
name.  In  genera!  anything  following  the  first  dot  may  be  omitted  if  it  is  the  same  as  the  domain 
from  which  you  are  sending  the  message.  For  example,  a  user  on  “calder .Berkeley .ARPA’*  could 
send  to  “eric@monet'’  without  adding  the  “.Berkeley .ARP A”  since  it  is  the  same  on  both  sending 
and  receiving  hosts. 

Certain  other  abbreviations  may  be  permitted  as  special  cases.  For  example,  at  Berkeley 
ARPANET  hosts  can  be  referenced  without  adding  the  “.ARPA”  as  long  as  their  names  do  not 
conflict  with  a  local  host  name. 

Compatibility.  Certain  old  address  formats  are  converted  to  the  new  format  to  provide 
compatibility  with  the  previous  mail  system.  In  particular, 

host:user 

is  converted  to 

user@host 

to  be  consistent  with  the  rcp(lC)  command. 

Also,  the  syntax: 

hostiuser 

is  converted  to: 

user@host.UUCP 

This  is  normally  converted  back  to  the  “hostiuser”  form  before  being  sent  on  for  compatibility 
with  older  UUCP  hosts. 

The  current  implementation  is  not  able  to  route  messages  automatically  through  the  UUCP 
network.  This  feature  is  planned  for  the  4.2  release.  Until  that  time  you  must  explicitly  tell  the 
mail  system  which  hosts  to  send  your  message  through  to  get  to  your  final  destination. 

Case  Distinctions.  Domain  names  (i.e.,  anything  after  the  “@”  sign)  may  be  given  in  any  mixture 
of  upper  and  lower  case  with  the  exception  of  UUCP  hostnames.  Most  hosts  accept  any  mixture 
of  case  in  user  names,  with  the  notable  exception  of  MULTICS  sites. 

Differences  with  ARPA  Protocols.  Although  the  UNIX  addressing  scheme  is  based  on  the  ARPA 
mail  addressing  protocols,  there  are  some  significant  differences. 
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At  the  time  of  this  writing  the  only  “top  level”  domain  defined  by  ARPA  is  the  “.ARPA”  domain 
itself.  This  is  further  restricted  to  having  only  one  level  of  host  specifier.  That  is,  the  only 
addresses  that  ARPA  accepts  at  this  time  must  be  in  the  format  “user ©host .ARP A”  (where 
“host”  is  one  word).  In  particular,  addresses  such  as: 

eric@monet.Berkeley.ARPA 

are  not  currently  legal  under  the  ARPA  protocols.  For  this  reason,  these  addresses  are  converted 
to  a  different  format  on  output  to  the  ARPANET,  typically: 

eric%monet@Berkeley.ARPA 

Route-addrs.  Under  some  circumstances  it  may  be  necessary  to  route  a  message  through  several 
hosts  to  get  it  to  the  final  destination.  Normally  this  routing  is  done  automatically,  but 
sometimes  it  is  desirable  to  route  the  message  manually.  An  address  that  shows  these  relays  are 
termed  “route-addrs.”  These  use  the  syntax: 

<@hosta,@hostb:user@hostc> 

This  specifies  that  the  message  should  be  sent  to  hosta,  from  there  to  hostb,  and  finally  to  hostc. 
This  path  is  forced  even  if  there  is  a  more  efficient  path  to  hostc. 

Route-ad drs  occur  frequently  on  return  addresses,  since  these  are  generally  augmented  by  the 
software  at  each  host.  It  is  generally  possible  to  ignore  all  but  the  “user ©host”  part  of  the 
address  to  determine  the  actual  sender. 

Postmaster.  Every  site  is  required  to  have  a  user  or  user  alias  designated  “postmaster”  to  which 
problems  with  the  mail  system  may  be  addressed. 

CSNET.  Messages  to  CSNET  sites  can  be  sent  to  “user.host©UDel-Relay”, 

BERKELEY 

The  following  comments  apply  only  to  the  Berkeley  environment. 

Host  Names.  Many  of  the  old  familiar  host  names  are  being  phased  out.  In  particular,  single 
character  names  as  used  in  Berknet  are  incompatible  with  the  larger  world  of  which  Berkeley  is 
now  a  member.  For  this  reason  the  following  names  are  being  obsoleted.  You  should  notify  any 


correspondents  of  your  new  address  as  soon  as  possible. 

OLD 

NEW 

j  ingvax 

ucbingres 

P 

ucbcad 

r  arpavax 

ucbarpa 

V  CSV  ax 

ucbernie 

n 

ucbkim 

y 

ucbcory 

The  old  addresses  will  be  rejected  as  unknown  hosts  sometime  in  the  near  future, 

What*s  My  Address?  If  you  are  on  a  local  machine,  say  monet,  your  address  is 
your  name@monet.Berkeley  .ARPA 

However,  since  most  of  the  world  does  not  have  the  new  software  in  place  yet,  you  will  have  to 
give  correspondents  slightly  different  addresses.  From  the  ARPANET,  your  address  would  be: 

yourname%monet@Berkeley.ARPA 
From  UUCP,  your  address  would  be: 

ucbvaxlmonet.yourname 

Computer  Center.  The  Berkeley  Computer  Center  is  in  a  subdomain  of  Berkeley  so  that  they 
may  administer  their  own  name  space.  Messages  to  the  computer  center  should  be  addressed  to 
one  of: 

user©host.CC.Berkeley.ARPA 

user%host.CC@BerkeIey.ARPA 
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depending  on  where  the  message  is  being  sent  from.  The  ‘‘.Berkeley .ARP A”  may  be  omitted  if 
the  message  is  sent  from  inside  Berkeley. 

For  the  time  being  Computer  Center  hosts  are  known  within  the  Berkeley  domain,  i.e.,  the 
“.CC’*  is  optional.  However,  it  is  likely  that  this  situation  will  change  with  time  as  both  the 
Computer  Science  department  and  the  Computer  Center  grow. 

Bitnei.  Hosts  on  bitnet  may  be  accessed  using: 

user@host.BITNET 
This  works  from  4,2  machines. 
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NAME 

man  —  macros  to  typeset  manual 

SYNOPSIS 

nroff  —man  file 

troff  —man  file  ... 

DESCRIPTION 

These  macros  are  used  to  lay  out  pages  of  this  manual.  The  best  way  to  learn  how  to  use  the 
macros  is  to  take  an  existing  manual  page  and  hack  it  over  to  your  own  requirements. 

Any  text  argument  t  may  be  zero  to  six  words.  Quotes  may  be  used  to  include  blanks  in  a 
'word’.  If  text  is  empty,  the  special  treatment  is  applied  to  the  next  input  line  with  text  to  be 
printed.  In  this  way  J  may  be  used  to  italicize  a  whole  line,  or  .SM  followed  by  *3  to  make  small 
bold  letters. 

A  prevailing  indent  distance  is  remembered  between  successive  indented  paragraphs,  and  is  reset 
to  default  value  upon  reaching  a  non-indented  paragraph.  Default  units  for  indents  i  are  ens. 

Type  font  and  size  are  reset  to  default  values  before  each  paragraph,  and  after  processing  font 
and  size  setting  macros. 

These  strings  are  predefined  by  —man: 

\*R  ^(Reg)’  in  nroff, 

\*S  Change  to  default  type  size. 

FILES 

/usr/Iib/tmac/tmac.an 
SEE  ALSO 

troff(l),  nroff(l),  man(l) 

BUGS 

Relative  indents  don't  nest. 


REQUESTS 

Request 

Cause  If  no 

Explanation 

Break 

Argument 

.B  t 

no 

f=n.t.l.* 

Text  /  is  bold. 

.BI  1 

no 

i=nXA, 

Join  words  of  /  alternating  bold  and  italic. 

.BR  t 

no 

f=n.U. 

Join  words  of  t  alternating  bold  and  Roman. 

•DT 

no 

.5i  li... 

Restore  default  tabs. 

.HP  » 

yes 

i=p.i.* 

Set  prevailing  indent  to  u  Begin  paragraph  with  hanging  indent. 

.1  t 

no 

^=n.t,!. 

Text  t  is  italic. 

•IB  t 

no 

f=n.tJ. 

Join  words  of  t  alternating  italic  and  bold. 

.IP  *  f 

yes 

ttn 

X— 

Same  as  .TP  with  tag  x. 

.IR  1 

no 

/=n.t.l. 

Join  words  of  t  alternating  italic  and  Roman. 

.LP 

yes 

- 

Same  as  .PP. 

PD  d 

no 

d=.4v 

Interparagraph  distance  is  d. 

.PP 

yes 

- 

Begin  paragraph.  Set  prevailing  indent  to  .5i. 

.RE 

yes 

- 

End  of  relative  indent.  Set  prevailing  indent  to  amount  of  starting  .RS. 

.RB  t 

no 

/=n.t.l. 

Join  words  of  t  alternating  Roman  and  bold. 

.RI  i 

no 

^=n.t.l. 

Join  words  of  t  alternating  Roman  and  italic. 

-RS  i 

yes 

^p.i. 

Start  relative  indent,  move  left  margin  in  distance  i.  Set  prevailing  indent 

to  .5i  for  nested  indents. 

.SH  t 

yes 

^=n.t.l. 

Subhead. 

.SM  t 

no 

/=n.t.l. 

Text  t  is  small. 

,TH  rt  c  j  i;  myes 

- 

Begin  page  named  n  of  chapter  c;  x  is  extra  commentary,  e.g.  Mocal’,  for 
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page  foot  center;  v  alters  page  foot  left,  e.g.  ‘4th  Berkeley  Distribution’;  m 
alters  page  head  center,  e.g.  ‘Brand  X  Programmer’s  Manual’.  Set 
prevailing  indent  and  tabs  to  .5i. 

.TP  i  yes  t=p.i.  Set  prevailing  indent  to  i.  Begin  indented  paragraph  with  hanging  tag 

given  by  next  text  line.  If  tag  doesn’t  fit,  place  it  on  separate  line. 

*  n.t.l.  =  next  text  line;  p.i.  =  prevailing  indent 


468 


Last  change:  5  November  1984 


Sun  Release  2.0 


ME(7) 


TABLES 


ME(7) 


NAME 

me  —  macros  for  formatting  papers 


SYNOPSIS 

nroff  —me  [  options  |  file  ... 
troff  —me  [  options  j  file  ... 

DESCRIPTION 

This  package  of  nroff  and  troff  macro  definitions  provides  a  canned  formatting  facility  for  tech¬ 
nical  papers  in  various  formats.  When  producing  2-column  output  on  a  terminal,  filter  the 
output  through  cof(l). 

The  macro  requests  are  defined  below.  Many  nroff  and  troff  requests  are  unsafe  in  conjunction 
with  this  package,  however  these  requests  may  be  used  with  impunity  after  the  first  .pp: 


.bp  begin  new  page 

.br  break  output  line  here 

.sp  n  insert  n  spacing  lines 

.Is  n  (line  spacing)  n=l  single,  n=2  double  space 

.na  no  alignment  of  right  margin 

.ce  n  center  next  n  lines 

.ul  n  underline  next  n  lines 

.sz  +n  add  n  to  point  size 


Output  of  the  egn,  neqn,  refer,  and  tbl{l)  preprocessors  for  equations  and  tables  is  acceptable  as 
input. 


FILES 

/usr/lib/tmac/tmac.e 

/usr/lib/me/* 

SEE  ALSO 

eqn(l),  troff(l),  refer(l),  tbl(l) 

—me  Reference  Manual,  Eric  P.  Allman 
Writing  Papers  with  Nroff  Using  —me 

REQUESTS 

In  the  following  list,  “initialization”  refers  to  the  first  .pp,  .Ip,  .ip,  .np,  .sh,  or  .uh  macro.  This  list 
is  incomplete;  see  The  —me  Reference  Manual  for  interesting  details. 


Request  Initial  Cause  Explanation 
Value  Break 


.(c 

yes 

Begin  centered  block 

.(d 

no 

Begin  delayed  text 

•(f 

no 

Begin  footnote 

•0 

yes 

Begin  list 

•(q 

yes 

Begin  major  quote 

.(XX 

no 

Begin  indexed  item  in  index  x 

.(z 

no 

Begin  floating  keep 

.)c 

yes 

End  centered  block 

•)d 

yes 

End  delayed  text 

.)f 

yes 

End  footnote 

•)l 

yes 

End  list 

•)q 

yes 

End  major  quote 

.)x 

yes 

End  index  item 

.)z 

yes 

End  floating  keep 

.++  m  - 

no 

Define  paper  section,  m  defines  the  part  of  the  paper,  and  can  be  C  (chapter), 
A  (appendix),  P  (preliminary,  e.g.,  abstract,  table  of  contents,  etc.),  B 
(bibliography),  RC  (chapters  renumbered  from  page  one  each  chapter),  or  RA 
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(appendix  renumbered  from  page  one). 


.+c  T 

- 

yes 

Begin  chapter  (or  appendix,  etc.,  as  set  by  .++).  T  is  the  chapter  title. 

.Ic 

1 

yes 

One  column  format  on  a  new  page. 

.2c 

1 

yes 

Two  column  format. 

.EN 

yes 

Space  after  equation  produced  by  eqn  or  neqn. 

.EQ  X  y 

yes 

Precede  equation;  break  out  and  add  space.  Equation  number  is  y.  The 
optional  argument  x  may  be  /  to  indent  equation  (default),  L  to  left-adjust  the 
equation,  or  (7  to  center  the  equation. 

,TE 

- 

yes 

End  table. 

.TH 

- 

yes 

End  heading  section  of  table. 

.TS  X 

- 

yes 

Begin  table;  if  x  is  /f  table  has  repeated  heading. 

.ac  A  N 

- 

no 

Set  up  for  ACM  style  output-  A  is  the  Author's  name(s),  N  is  the  total 
number  of  pages.  Must  be  given  before  the  first  initialization. 

,b  X 

no 

no 

Print  X  in  boldface;  if  no  argument  switch  to  boldface. 

.ba  +n 

0 

yes 

Augments  the  base  indent  by  n.  This  indent  is  used  to  set  the  indent  on 
regular  text  (like  paragraphs). 

.be 

no 

yes 

Begin  new  column 

.bi  X 

no 

no 

Print  X  in  bold  italics  (nofill  only) 

.bx  X 

no 

no 

Print  in  a  box  (nofill  only). 

.ef  "x  ^y  'z ' 

^  * 

no 

Set  even  footer  to  x  y  z 

.eh  'x'y'z' 

/  ^  ^  / 

no 

Set  even  header  to  x  y  z 

.fo  X  y  z 

0  0  *  f 

no 

Set  footer  to  x  y  z 

,hx 

- 

no 

Suppress  headers  and  footers  on  next  page. 

.he  'x  'y  'z ' 

0  0  0  0 

no 

Set  header  to  x  y  z 

.hi 

- 

yes 

Draw  a  horizontal  line 

.i  X 

no 

no 

Italicize  x;  if  x  missing,  italic  text  follows. 

.ip  xy 

no 

yes 

Start  indented  paragraph,  with  hanging  tag  j.  Indentation  is  y  ens  (default  5). 

.Ip 

yes 

yes 

Start  left-blocked  paragraph. 

,lo 

no 

Read  in  a  file  of  local  macros  of  the  form  •♦ar.  Must  be  given  before 
initialization. 

.np 

1 

yes 

Start  numbered  paragraph. 

.of  'x'y'z* 

^  ^  ^ 

no 

Set  odd  footer  to  x  y  z 

.oh  'x^y'z' 

^  ^  ^  ^ 

no 

Set  odd  header  to  x  y  z 

.pd 

- 

yes 

Print  delayed  text. 

.pp 

no 

yes 

Begin  paragraph.  First  line  indented. 

.r 

yes 

no 

Roman  text  follows. 

.re 

no 

Reset  tabs  to  default  values. 

.sc 

no 

no 

Read  in  a  file  of  special  characters  and  diacritical  marks.  Must  be  given  before 
initialization. 

.sh  n  X 

- 

yes 

Section  head  follows,  font  automatically  bold,  n  is  level  of  section,  z  is  title  of 
section. 

.sk 

no 

no 

Leave  the  next  page  blank.  Only  one  page  is  remembered  ahead. 

.sz  +n 

lOp 

no 

Augment  the  point  size  by  n  points. 

.th 

no 

no 

Produce  the  paper  in  thesis  format.  Must  be  given  before  initialization. 

.tp 

no 

yes 

Begin  title  page. 

.tl  z 

• 

no 

Underline  argument  (even  in  troff)*  (Nofill  only). 

.uh 

- 

yes 

Like  .sh  but  unnumbered. 

.xp  X 

- 

no 

Print  index  x. 
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NAME 

ms  —  text  formatting  macros 
SYNOPSIS 

nroff  —ms  [  options  j  file 
troff  —ms  [  options  ]  file 

DESCRIPTION 

This  package  of  nroff  and  iroff  macro  definitions  provides  a  formatting  facility  for  various  styles 
of  articles,  theses,  and  books.  When  producing  2-coIumn  output  on  a  terminal  or  lineprinter,  or 
when  reverse  line  motions  are  needed,  filter  the  output  through  col{l).  All  external  —ms  macros 
are  defined  below. 

Note  that  this  —ms  macro  package  is  an  extended  version  written  at  Berkeley  and  is  a  superset 
of  the  standard  —  ms  macro  packages  as  supplied  by  Bell  Labs.  Some  of  the  Bell  Labs  macros 
have  been  removed;  for  instance,  it  is  assumed  that  the  user  has  little  interest  in  producing 
headers  stating  that  the  memo  was  generated  at  Whippany  Labs. 

Many  nroff  and  troff  requests  are  unsafe  in  conjunction  with  this  package.  However,  the  first 
four  requests  below  may  be  used  with  impunity  after  initialization,  and  the  last  two  may  be  used 
even  before  initialization: 

.bp  begin  new  page 

,br  break  output  line 

.sp  n  insert  n  spacing  lines 

,ce  n  center  next  n  lines 

.Is  n  line  spacing:  n=l  single,  n=2  double  space 
.na  no  alignment  of  right  margin 

Font  and  point  size  changes  with  \f  and  \s  are  also  allowed;  for  example,  “\nword\fR”  will 
italicize  word.  Output  of  the  ^6/(1),  eqn{i)  and  re/er(l)  preprocessors  for  equations,  tables,  and 
references  is  acceptable  as  input. 

FILES 

/usr  /lib/tmac /tmac  .s 
/usr/lib/ms/ms.??? 

SEE  ALSO 

eqn(l),  refer(l),  tbl(l),  troff(l) 

Formatting  Documents  with  the  —ms  Macro  Package  in 
Editing  and  Text  Processing  on  the  Sun  Workstation  and  the 
Beginner^s  Guide  to  the  Sun  Workstation. 

REQUESTS 


Macro 

Name 

Initial 

Value 

Break? 

Reset? 

Explanation 

.AB  X 

— 

y 

begin  abstract;  if  ;r=no  don^t  label  abstract 

.AE 

y 

end  abstract 

.AI 

y 

author’s  institution 

-AM 

— 

n 

better  accent  mark  definitions 

.AU 

— 

y 

author’s  name 

.B  z 

— 

n 

embolden  j;  if  no  z,  switch  to  boldface 

.B1 

— 

y 

begin  text  to  be  enclosed  in  a  box 

.B2 

— 

y 

end  boxed  text  and  print  it 

•BT 

date 

n 

bottom  title,  printed  at  foot  of  page 

.BX* 

— 

n 

print  word  j  in  a  box 

.CM 

if  t 

n 

cut  mark  between  pages 

.CT 

— 

y,y 

chapter  title:  page  number  moved  to  CF  (TM  only) 

.DA  z 

if  n 

n 

force  date  x  at  bottom  of  page;  today  if  no  z 
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.DE 

- 

y 

end  display  (unfilled  text)  of  any  kind 

•DS  xy 

I 

y 

begin  display  with  keep;  ar=I,L,C,B;  y=indent 

.ID  y 

8n,.5i 

y 

indented  display  with  no  keep;  i/— indent 

.LD 

- 

y 

left  display  with  no  keep 

•CD 

- 

y 

centered  display  with  no  keep 

.BD 

— 

y 

block  display;  center  entire  block 

.EF  X 

— 

n 

even  page  footer  z  (3  part  as  for  .tl) 

.EH  X 

— 

n 

even  page  header  z  (3  part  as  for  .tl) 

.EN 

— 

y 

end  displayed  equation  produced  by  egn 

.EQ  X  y 

- 

y 

break  out  equation;  z=L,I,C;  |/=equation  number 

.FE 

— 

n 

end  footnote  to  be  placed  at  bottom  of  page 

.FP 

— 

n 

numbered  footnote  paragraph;  may  be  redefined 

.FS  X 

— 

n 

start  footnote;  z  is  optional  footnote  label 

.HD 

undef 

n 

optional  page  header  below  header  margin 

.1  X 

— 

n 

italicize  z;  if  no  z,  switch  to  italics 

JP  X  y 

- 

y,y 

indented  paragraph,  with  hanging  tag  z;  i/=indent 

.DC  X  y 

- 

y 

index  words  z  y  and  so  on  (up  to  5  levels) 

.KE 

— 

n 

end  keep  of  any  kind 

.KF 

- 

n 

begin  floating  keep;  text  fills  remainder  of  page 

.KS 

— 

y 

begin  keep;  unit  kept  together  on  a  single  page 

.LG 

— 

n 

larger;  increase  point  size  by  2 

.LP 

- 

yj 

left  (block)  paragraph. 

.MC  X 

- 

yj 

multiple  columns;  z=*column  width 

.ND  X 

if  t 

n 

no  date  in  page  footer;  z  is  date  on  cover 

.NHxy 

— 

y,y 

numbered  header;  z—level,  z=0  resets,  z==S  sets  to  i/ 

.ML 

lOp 

n 

set  point  size  back  to  normal 

.OF  X 

- 

n 

odd  page  footer  z  (3  part  as  for  .tl) 

.OH  X 

- 

n 

odd  page  header  z  (3  part  as  for  .tl) 

.PI 

if  TM 

n 

print  header  on  1st  page 

.PP 

- 

yj 

paragraph  with  first  line  indented 

.PT 

-  - 

n 

page  title,  printed  at  head  of  page 

.PXa; 

- 

y 

print  index  (table  of  contents);  z=no  suppresses  title 

•QP 

— 

yj 

quote  paragraph  (indented  and  shorter) 

.R 

on 

n 

return  to  Roman  font 

.RE 

5n 

yj 

retreat:  end  level  of  relative  indentation 

.RP  X 

— 

n 

released  paper  format;  z=no  stops  title  on  1st  page 

.RS 

5n 

yj 

right  shift:  start  level  of  relative  indentation 

•SH 

— 

yj 

section  header,  in  boldface 

.SM 

- 

n 

smaller;  decrease  point  size  by  2 

.TA 

8n,5n 

n 

set  tabs  to  8n  16n  ...  (nroff)  5n  lOn  ...  (troff) 

.TC  X 

- 

y 

print  table  of  contents  at  end;  z«“no  suppresses  title 

.TE 

- 

y 

end  of  table  processed  by  tbi 

.TH 

- 

y 

end  multi-page  header  of  table 

.TL 

- 

y 

title  in  boldface  and  two  points  larger 

■TM 

off 

n 

UC  Berkeley  thesis  mode 

,TS  X 

— 

y,y 

begin  table;  if  z»=H  table  has  multi-page  header 

.UL  X 

n 

underline  z,  even  in  (roff 

.UX  X 

- 

n 

UNIX;  trademark  message  first  time;  z  appended 

.XA  X  y 

— 

y 

another  index  entry;  z^^page  or  no  for  none;  j^«indent 

.XE 

- 

y 

end  index  entry  (or  series  of  .DC  entries) 

.XP 

— 

yj 

paragraph  with  first  line  exdented,  others  indented 

.XSxy 

— 

y 

begin  index  entry;  z«*page  or  no  for  none;  ^/••indent 

.1C 

on 

y,y 

one  column  format,  on  a  new  page 
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y,y  begin  two  column  format 

n  beginning  of  refer  reference 

n  end  of  unclassifiable  type  of  reference 
n  N=  l:journal-article,  2:book,  3:book-article,  4:report 
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REGISTERS 

Formatting  distances  can  be  controlled  in  — m*  by  means  of  built-in  number  registers.  For 
example,  this  sets  the  line  length  to  6.5  inches: 

.nr  LL  6.5i 

Here  is  a  table  of  number  registers  and  their  default  values: 


Name 

Register  Controls 

Takes  Effect  Default 

PS 

point  size 

paragraph 

10 

VS 

vertical  spacing 

paragraph 

12 

LL 

line  length 

paragraph 

6i 

LT 

title  length 

next  page 

same  as  LL 

FL 

footnote  length 

next  PS 

5.5i 

PD 

paragraph  distance 

paragraph 

Iv  (if  n),  .3v  (if  t) 

DD 

display  distance 

displays 

Iv  (if  n),  .5v  (if  t) 

PI 

paragraph  indent 

paragraph 

5n 

QI 

quote  indent 

next  .QP 

5n 

FI 

footnote  indent 

next  .FS 

2n 

PO 

page  offset 

next  page 

0  (if  n),  ~li  (if  t) 

HM 

header  margin 

next  page 

li 

FM 

footer  margin 

next  page 

li 

FF 

footnote  format 

next  .FS 

0  (1,  2,  3  available) 

When  resetting  these  values,  make  sure  to  specify  the  appropriate  units.  Setting  the  line  length 
to  7,  for  example,  will  result  in  output  with  one  character  per  line.  Setting  FF  to  1  suppresses 
footnote  superscripting;  setting  it  to  2  also  suppresses  Indentation  of  the  first  line;  and  setting  it 
to  3  produces  an  .IP-like  footnote  paragraph. 

Here  is  a  list  of  string  registers  available  in  —ms;  they  may  be  used  anywhere  in  the  text: 


Name 

String’s  Function 

\*Q 

quote  in  nroff,  “  in  troff ) 

\*u 

unquote  (”  in  nroff,  ”  in  troff ) 

\*- 

dash  (-  in  nroff,  —  in  troff ) 

\*(MO 

month  (month  of  the  year) 

\*(DY 

day  (current  date) 

automatically  numbered  footnote 

\*' 

acute  accent  (before  letter) 

\*' 

grave  accent  (before  letter) 

\*. 

circumflex  (before  letter) 

\*. 

cedilla  (before  letter) 

\*: 

umlaut  (before  letter) 

V- 

tilde  (before  letter) 

When  using  the  extended  accent  mark  definitions  available  with  .AM,  these  strings  should  come 
after,  rather  than  before,  the  letter  to  be  accented. 

BUGS 

Floating  keeps  and  regular  keeps  are  diverted  to  the  same  space,  so  they  cannot  be  mixed 
together  with  predictable  results. 
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NAME 

intro  —  introduction  to  system  maintenance  and  operation  commands 
DESCRIPTION 

This  section  contains  information  related  to  system  bootstrapping,  operation  and  maintenance 
and  describes  all  the  server  processes  and  daemons  which  run  on  the  system. 

Disk  formatting  and  labelling  is  done  by  diag{SS)  which  participates  in  most  system  bootstraps. 
Bootstrapping  of  the  system  is  described  in  reboot{S).  The  standard  set  of  commands  run  by  the 
system  when  it  boots  is  described  in  rc(8).  Related  commands  include  ones  to  check  the  con¬ 
sistency  of  file  systems  fsck{S),  mount  and  unmount  file  systems  mount{S)  and  add 

swap  devices  5u;apc>n(8),  cause  all  outstanding  disk  I/O  to  complete  6ync{S)f  shutdown  or  reboot 
a  running  system  skutdown{S)y  haU{S),  and  reJoo^(8),  set  the  time  on  a  machine  from  the  time  on 
another  machine  rdafe(8). 

Creation  of  file  systems  is  discussed  in  mjfc/?(8)  and  new;/?(8).  File  system  performance  parame¬ 
ters  are  adjustable  with  tunefs{S).  File  system  saves  and  restores  are  described  in  rfump(8)  and 
re$tore{S), 

Procedures  for  adding  new  users  to  a  system  are  described  in  arfrfuser(8)  using  t;jpu;(8). 

Other  programs  useful  when  the  system  crashes  or  hardware  is  broken  include  gxte8t[SS)  which 
tests  the  frame  buffer  on  a  workstation,  tmemfe^^(8S)  which  tests  the  memory,  cra^A(8S)  which 
describes  what  happens  when  the  system  crashes,  8av€core{S)  and  analgze{S)  which  can  be  used 
to  analyze  system  crash  dumps.  Occasionally  useful  as  adjuncts  to  the  f8ck[S)  file  system  repair 
program  are  c/rf(8),  d€keck{S),  icheck{S)y  and  nch€ck[S), 

Configuring  a  new  version  of  the  UNIX  kerne!  requires  using  the  program  config{S);  major  sys¬ 
tem  bootstraps  often  require  the  use  of  mkproto{S).  New  devices  are  made  in  the  /dev  directory 
when  device  drivers  are  added  to  the  system  by  using  the  makedev{S)  and  mknod[S)  commands. 
If  you  have  source,  you  will  use  the  ms^aW(8)  command  to  reinstall  freshly  compiled  programs, 
and  catman{S)  to  reformat  the  pre-for matted  version  of  the  manual. 

Resource  accounting  is  enabled  by  the  <iccfon(8)  command,  and  summarized  by  sa{S),  Login 
time  accounting  is  performed  by  <ic(8). 

A  number  of  service  and  daemon  processes  are  described  here.  The  update^)  daemon  forces 
delayed  disk  I/O  to  occur  and  cr<?f2(8)  runs  periodic  events  (such  as  removing  temporary  files 
from  the  disk  periodically).  The  rfniesp(8)  process  is  invoked  by  cron  and  keeps  the  system  error 
log.  The  mt7(8)  process  is  the  initial  process  created  when  UNIX  boots  and  manages  the  reboot 
process  and  creates  the  initial  login  prompts  on  the  various  system  terminals  through  the  services 
of  getty[^\  The  Internet  super-server  inetdi^Q)  invokes  all  other  internet  servers  as  needed. 
These  servers  include  the  remote  shell  servers  rshd[SC)  and  rexecd{SC)  the  remote  login  server 
r/oifmrf(8C)  the  FTP  and  TELNET  daemons  ftpd{SC)  and  ^e/ne/rf(8C),  the  TFTP  daemon 
tftpd{SC)  and  the  mail  arrival  notification  daemon  com?a^(8C).  Other  network  daemons  include 
the  'load  average/who  is  logged  in^  daemon  rwhod{8C),  the  routing  daemon  rou/cd(8C),  and  the 
mail  daemon  ^endmut7(8). 

If  network  protocols  are  being  debugged,  then  the  protocol  debugging  trace  program  ^rp^(8C)  is 
often  useful.  Remote  magnetic  tape  access  is  provided  by  rsh  and  rm^(8C).  Remote  line  printer 
access  is  provided  by  /pd(8)  and  control  over  the  various  print  queues  is  had  through  /pc(8). 
Printer  cost  accounting  is  done  through  pac(8). 

Network  host  tables  may  be  gotten  from  the  ARPA  NIC  using  getiahl€{SC)  and  converted  to 
UNIX  usable  format  using  htable{S), 

RCP  and  NFS  daemons  include: 

/ectfportmap 

used  by  rpc  based  services. 
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feic/yphind 

used  by  the  yellowpages  to  locate  the  yellowpages  server. 

/  etc/hiod 

used  by  NFS  clients  to  read  ahead  to,  and  write  behind  from,  network  file  systems. 
I  ecifnfsd 

only  on  NFS  servers,  the  server’s  counterpart  to  leic/hiod. 
letclypstTv 

implements  the  yellowpages  server,  typically  on  each  nd  server. 

(ubt!  eiclrpc^rstatd 

the  server  counterpart  ofthe  remote  speedometer  tools. 

fusrl  eic,moxintd 

the  server  counterpart  to  mount. 

f  usrj  etcf  rcpswalld 

used  for  broadcasting  messages  over  the  network. 

LIST  OF  PROGRAMS 


Program 

Appears  on  Page 

Description 

ac 

ac.8 

login  accounting 

accton 

sa.8 

system  accounting 

adbgen 

adbgen.8 

generate  adb  script 

adduser 

adduser  .8 

procedure  for  adding  new  users 

analyze 

analyze. 8 

Virtual  UNIX  postmortem  crash  analyzer 

arp 

arp. 8c 

address  resolution  display  and  control 

c  atm  an 

catman.8 

create  the  cat  files  for  the  manual 

chown 

chown.8 

change  owner 

clri 

clri  .8 

clear  i-node 

comsat 

comsat.8c 

biff  server 

config 

config.8 

build  system  configuration  files 

crash 

crash.8s 

what  happens  when  the  system  crashes 

cron 

cron.8 

clock  daemon 

dcheck 

dcheck.8 

file  system  directory  consistency  check 

diag 

diag.8s 

General-purpose  stand-alone  utility  package 

dmesg 

dmesg.8 

collect  system  diagnostic  messages  to  form  error  log 

dump 

dump.8 

incremental  file  system  dump 

dumpfs 

dumpfs.S 

dump  file  system  information 

expire 

expire. 8 

remove  outdated  news  articles 

fastboot 

fastboot.8 

reboot/halt  the  system  without  checking  the  disks 

fasthalt 

fastboot.8 

reboot/halt  the  system  without  checking  the  disks 

fsck 

fsck. 8 

file  system  consistency  check  and  interactive  repair 

ftpd 

ftpd  .8c 

DARPA  Internet  File  Transfer  Protocol  server 

gettable 

gettable.Sc 

get  NIC  format  host  tables  from  a  host 

getty 

getty  .8 

set  terminal  mode 

gxtest 

gxtest.8s 

stand  alone  test  for  the  Sun  video  graphics  board 

halt 

halt.8 

stop  the  processor 

htable 

htable,8 

convert  NIC  standard  format  host  tables 

icheck 

icheck.8 

file  system  storage  consistency  check 

ifconfig 

ifconfig.Sc 

configure  network  interface  parameters 

imemtest 

imemtcst.8s 

stand  alone  memory  test 

inetd 

inetd  .8c 

internet  services  daemon 

init 

init.8 

process  control  initialization 

iostat 

iostat  .8 

report  I/O  statistics 
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kgmon 

kgmon.8 

generate  a  dump  of  the  operating  system’s  profile  buffers 

Ipc 

lpc.8 

line  printer  control  program 

Ipd 

Ipd  .8 

line  printer  daemon 

MAKEDEV 

makedev.8 

make  system  special  files 

makekey 

makekey.8 

generate  encryption  key 

mkfs 

mkfs.8 

construct  a  file  system 

mknod 

mknod  .8 

build  special  file 

mk  proto 

mkproto.8 

construct  a  prototype  file  system 

mount 

mount.8 

mount  and  dismount  file  system 

ncheck 

ncheck.8 

generate  names  from  i-numbers 

nd 

nd.Sc 

network  disk  control 

netstat 

netstat.8 

show  network  status 

newaliases 

newaliases.8 

rebuild  the  data  base  for  the  mail  aliases  file 

newfs 

newfs.8 

construct  a  new  file  system 

pac 

pac  .8 

printer/plotter  accounting  information 

pstat 

pstat.8 

print  system  facts 

quot 

quot.8 

summarize  file  system  ownership 

re 

rc.8 

command  script  for  auto-reboot  and  daemons 

rdate 

rdate.8 

set  system  date  from  a  remote  host 

reboot 

reboot.8 

UNIX  bootstrapping  procedures 

recnews 

recnews.8 

receive  unprocessed  articles  via  mail 

renice 

renice.8 

alter  priority  of  running  processes 

restore 

restore.8 

incremental  file  system  restore 

rexecd 

rexecd.Sc 

remote  execution  server 

rlogind 

rlogind  .8c 

remote  login  server 

rmail 

rmail.8 

handle  remote  mail  received  via  uucp 

o 

rmt 

rmt.Sc 

remote  magtape  protocol  module 

w' 

route 

route.Sc 

manually  manipulate  the  routing  tables 

routed 

routed.Sc 

network  routing  daemon 

rshd 

rshd. 8c 

remote  shell  server 

rwhod 

rwhod  .8c 

system  status  server 

sa 

sa,8 

system  accounting 

savecore 

savecore.8 

save  a  core  dump  of  the  operating  system 

sendmail 

sendmail.8 

send  mail  over  the  internet 

sendnews 

sendnews.8 

send  news  articles  via  mail 

shutdown 

shutdown.8 

close  down  the  system  at  a  given  time 

sticky 

sticky  .8 

executable  files  with  persistent  text 

swapon 

swapon.8 

specify  additional  device  for  paging  and  swapping 

sync 

sync.8 

update  the  super  block 

syslog 

sys!og.8 

log  systems  messages 

telnetd 

telnetd.Sc 

DARPA  TELNET  protocol  server 

tftpd 

tftpd. 8c 

DARPA  Trivial  File  Transfer  Protocol  server 

timed 

timed. 8c 

DARPA  Time  server 

trpt 

trpt.Sc 

transliterate  protocol  trace 

tunefs 

tunefs. 8 

tune  up  an  existing  file  system 

umount 

mount.8 

mount  and  dismount  file  system 

update 

up  date  .8 

periodically  update  the  super  block 

uuclean 

uuclean.8c 

uucp  spool  directory  clean-up 

uurec 

uurec.8 

receive  processed  news  articles  via  mail 

vipw 

vipw.8 

edit  the  password  file 

vmstat 

vmstat  .8 

report  virtual  memory  statistics 

o 
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NAME 

ac  —  login  accounting 
SYNOPSIS 

/usp/etc/ac  |  — w  wtmp  ]  [  — p  ]  |  — d  [  [  people  j  ... 

DESCRIPTION 

Ac  produces  a  printout  giving  connect  time  for  each  user  who  has  logged  in  during  the  life  of  the 
current  wimp  file,  A  total  is  also  produced. 

The  accounting  file  (usr/ admfwimp  is  maintained  by  mil  and  login.  Neither  of  these  programs 
creates  the  file,  so  if  it  does  not  exist  no  connect-time  accounting  is  done.  To  start  accounting,  it 
should  be  created  with  length  0.  On  the  other  hand  if  the  file  is  left  undisturbed  it  will  grow 
without  bound,  so  periodically  any  information  desired  should  be  collected  and  the  file  truncated. 

OPTIONS 

— w  specifies  an  alternate  wimp  file. 

— p  prints  individual  totals;  without  this  option,  only  totals  are  printed. 

— d  printout  for  each  midnight  to  midnight  period.  Any  people  will  limit  the  printout  to  only 

the  specified  login  names.  If  no  wtmp  file  is  given,  f  ubt! admf  wtmp  is  used. 

FILES 

/usr/adm/wtmp 
SEE  ALSO 

init(8),  sa(8),  login(l),  utmp(5). 
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NAME 

adbgen  —  generate  adb  script 
SYNOPSIS 

/usr/lib/adb/sdbgen  file.adb ... 

DESCRIPTION 

Adbgen  makes  it  possible  to  write  ad6(l)  scripts  that  do  not  contain  hard-coded  dependencies  on 
structure  member  offsets.  The  input  to  adbgen  is  a  file  named  Jile,tAb  which  contains  adbgen 
header  information,  then  a  null  line,  then  the  name  of  a  structure,  and  finally  an  adb  script. 
Adbgen  only  deals  with  one  structure  per  file;  ail  member  names  are  assumed  to  be  in  this  struc¬ 
ture.  The  output  of  adbgen  is  an  adb  script  in  file.  Adbgen  operates  by  generating  a  C  program 
which  determines  structure  member  offsets  and  sizes,  which  in  turn  generates  the  adb  script. 

The  header  lines,  up  to  the  null  line,  are  copied  verbatum  into  the  generated  C  program.  Typi¬ 
cally  these  include  C  #lnclude  statements  to  include  the  header  files  containing  the  relevant 
structure  declarations. 

The  adb  script  part  may  contain  any  valid  adb  commands  (see  <idi(l)),  and  may  also  contain 
adbgen  requests,  each  enclosed  in  {}s.  Request  types  are: 

1  Print  a  structure  member.  The  request  form  is  {member, /armol}.  Member  is  a  member 
name  of  the  structure  given  earlier,  and  format  is  any  valid  adb  format  request.  For 
example,  to  print  the  p..pid  field  of  the  proc  structure  as  a  decimal  number,  you  would 
write  {p_pld,d}. 

2  Reference  a  structure  member.  The  request  form  is  {♦member, Afem^er  is  the 
member  name  whose  value  is  desired,  and  base  is  an  adb  register  name  which  contains 
the  base  address  of  the  structure.  For  example,  to  get  the  p^pid  field  of  the  proc  struc¬ 
ture,  you  would  get  the  proc  structure  address  in  an  adb  register,  say  <f,  and  write 

{♦p_pid,<f}. 

3  Tell  adbgen  that  the  offset  is  ok.  The  request  form  is  {OFFSETOK).  This  is  useful 
after  invoking  another  adb  script  which  moves  the  adb  dot. 

4  Get  the  size  of  the  stmciurc.  The  request  form  is  {SIZEOF}.  Adbgen  replaces  this 
request  with  the  size  of  the  structure.  This  is  useful  in  incrementing  a  pointer  to  step 
through  an  array  of  structures. 

5  Get  the  offset  to  the  end  of  the  structure.  The  request  form  is  {END}.  This  is  useful 
at  the  end  of  the  structure  to  get  adb  to  align  the  dot  for  printing  the  next  structure 
member. 

Adbgen  keeps  track  of  the  movement  of  the  adb  dot  and  emits  adb  code  to  move  forward  or 
backward  as  necessary  before  printing  any  structure  member  in  a  script.  Adbgen^s  model  of  the 
behavior  of  adb's  dot  is  simple:  it  is  assumed  that  the  first  line  of  the  script  is  of  the  form 
struct^addresa/adb  text  and  that  subsequent  lines  are  of  the  form  -h/ad6  text.  This  causes  the 
adb  dot  to  move  in  a  sane  fashion.  Adbgen  does  not  check  the  script  to  ensure  that  these  limita¬ 
tions  are  met.  Adbgen  also  checks  the  size  of  the  structure  member  against  the  size  of  the  adb 
format  code  and  warns  you  if  they  are  not  equal. 

EXAMPLE 

If  there  were  an  include  file  x.h  which  contained: 

struct  X  { 

char  *x_cp; 
char  x_c; 
int  xj; 

}; 
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Then  an  adbgen  file  (call  it  script.adb)  to  print  It  would  be: 

#include  "x.h" 

X 

./"x_cp"l6t"x_c"8t"xJ"n{x_cp,X}{x_c,C}{xJ,D} 

After  running  adbgen  the  output  file  script  would  contain: 

./"x_cp"l6t"x_c"8t"xJ"nXC+D 
To  invoke  the  script  you  would  type: 

x$<script 

DIAGNOSTICS 

Warnings  about  structure  member  sizes  not  equal  to  ctdb  format  items  and  complaints  about 
badly  formatted  requests.  The  C  compiler  complains  if  you  reference  a  structure  member  that 
does  not  exist.  It  also  complains  about  &  before  array  names;  these  complaints  may  be  ignored. 

FILES 

/usr/lib/adb/*  adb  scripts  for  debugging  the  kernel 
SEE  ALSO 

adb(I),  Using  ADB  to  Debug  the  UNIX  Kernel 

BUGS 

Adb  syntax  is  ugly;  there  should  be  a  higher  level  interface  for  generating  scripts. 

Structure  members  which  are  bit  fields  cannot  be  handled  because  C  will  not  give  the  address  of 
a  bit  field.  The  address  is  needed  to  determine  the  offset. 
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NAME 

adduser  —  procedure  for  adding  new  users 
DESCRIPTION 

To  add  a  new  user  account  to  the  system,  you  must  do  at  least  the  following  things: 

1.  Create  an  entry  in  the  system  password  file  for  that  user. 

2.  Make  a  ‘home  directory’  for  the  user  and  make  sure  that  the  user  is  the  owner  of  their 
home  directory. 

3.  Set  up  some  skeletal  profile  files  for  the  new  user. 

These  steps  are  described  in  detail  below. 

Making  an  entry  in  the  password  file:  A  new  user  must  choose  a  login  name,  which  must 
not  already  appear  in  fetcfpasswd.  An  account  can  be  added  by  editing  a  line  into  the 
/etc/passwd  file;  this  must  be  done  with  the  password  file  locked,  for  example,  by  using  t;ipu?(8). 

A  new  user  is  given  a  group  and  user  id.  User  id’s  should  be  distinct  across  a  system,  since  they 
are  used  to  control  access  to  files.  Typically,  users  working  on  similar  projects  will  be  put  in  the 
same  group.  System  staff  is  group  ‘10’  for  historical  reasons,  and  the  super-user  is  in  this  group. 

A  skeletal  account  for  a  new  user  ‘francine’  would  look  like: 

francine : ;  235 : 20  s  &  Featherstonehaugh  s  /usr /francine  s  /bin/csh 

Fields  in  the  password  file  have  the  following  meanings: 

1.  Login  name  (‘francine’).  The  login  name  is  limited  to  eight  characters  in  length. 

2.  Encrypted  password.  Typically,  this  field  is  left  empty  for  a  new  user  so  that  the  first  time 
they  log  in  they  don’t  need  a  password.  They  can  then  set  their  password  to  whatever  they 
like  using  the  pa8swd{l)  command. 

3.  User  ID.  The  user  ID  is  a  number  which  identifies  that  user  uniquely  in  the  system.  All  files 
that  that  user  creates  have  this  number  stored  in  the  data  block  that  describes  the  file  and 
commands  such  as  k(l)  use  that  number  to  look  in  the  password  file  to  get  the  user’s  name 
when  identifying  the  owner  of  the  file.  For  this  reason,  you  cannot  just  go  merrily  changing 
this  number  at  random. 

4.  Group  ID.  The  group  ID  is  a  number  which  identifies  the  group  to  which  the  user  belongs. 
All  files  that  that  user  creates  have  this  number  stored  in  the  data  block  that  describes  the 
file  and  commands  such  as  ts{l)  use  that  number  to  look  in  the  groups  file  to  get  the  groups 
name  when  identifying  the  group  ownership  of  the  file. 

5.  This  field  is  called  the  ‘GCOS’  field  (from  earlier  implementation  of  the  UNIX  system)  and  is 
traditionally  used  to  hold  the  user’s  full  name.  Some  installations  have  other  information 
encoded  in  this  field.  From  this  information  we  can  tell  that  Francine’s  real  name  is  ‘Francine 
Featherstonehaugh’.  The  &  here  is  a  shorthand  for  the  user’s  login  name. 

6.  User’s  home  directory.  This  is  the  directory  in  which  that  user  is  ‘positioned’  when  they  log 
in. 

7.  Initial  shell  which  this  user  will  see  on  login.  If  this  field  is  empty,  sA(l)  is  used  as  the  initial 
shell. 

Making  a  home  directory  for  the  new  user:  now  you  make  a  home  directory  for  Francine. 
As  shown  in  the  password  file  entry  above,  Francine’s  home  directory  is  / usr f francine.  Francine 
must  be  the  owner  of  that  directory  in  order  to  create  files  there.  So  the  following  sequence 
would  suffice: 

tutorial#  mkdir  /usr/f^anclne 

tutorial#  /ctc/chown  francine  /uer/franclne 

tutorial# 
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Setting  up  skeletal  profile  files:  It  is  useful  to  give  new  users  some  help  in  getting  started, 
supplying  them  with  a  few  skeletal  files  such  as  .profile  if  they  use  /bin/ ah  as  the  shell,  or  .eshrc 
and  .login  if  they  use  /bin/cak  as  the  shell.  New  users  should  be  given  copies  of  these  files  which, 
for  instance,  arrange  to  use  facf(l)  automatically  at  each  login. 

FILES 

/etc/passwd  password  file 

SEE  ALSO 

passwd(l),  mkdir(l),  chown(8),  chsh(l),  passwd(5),  vipw(8) 
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NAME 

analyze  -  Virtual  UNIX  postmortem  crash  analyzer 
SYNOPSIS 

/usr  /etc /analyse  I  -B  swapfile  j  [  -f  1  I  -m  ]  [  -d  ]  [  -D  |  [  -v  |  corefile  |  system  | 
DESCRIPTION 

Analyze  is  the  post-mortem  analyzer  for  the  state  of  the  paging  system*  In  order  to  use  analyze 
you  must  arrange  to  get  a  image  of  the  memory  (and  possibly  the  paging  area)  of  the  system 
after  it  crashes  (see  cra^A(8S)). 

The  analyze  program  reads  the  relevant  system  data  structures  from  the  core  image  file  and 
indexing  information  from  /vmunlx  (or  the  specified  file)  to  determine  the  state  of  the  paging 
subsystem  at  the  point  of  crash.  It  looks  at  each  process  in  the  system,  and  the  resources  each  is 
using  in  an  attempt  to  determine  inconsistencies  in  the  paging  system  state.  Normally,  the  out¬ 
put  consists  of  a  sequence  of  lines  showing  each  active  process,  its  state  (whether  swapped  in  or 
not),  its  pOhVy  and  the  number  and  location  of  its  page  table  pages.  Any  pages  which  are  locked 
while  raw  i/o  is  in  progress,  or  which  are  locked  because  they  are  intransit  are  also  printed. 
(Intransit  text  pages  often  diagnose  as  duplicated;  you  will  have  to  weed  these  out  by  hand.) 

The  program  checks  that  any  pages  in  core  which  are  marked  as  not  modified  are,  in  fact,  identi¬ 
cal  to  the  swap  space  copies.  It  also  checks  for  non-overlap  of  the  swap  space,  and  that  the  core 
map  entries  correspond  to  the  page  tables.  The  state  of  the  free  list  is  also  checked. 

Options  to  analyze: 

— D  causes  the  diskmap  for  each  process  to  be  printed. 

— d  causes  the  (sorted)  paging  area  usage  to  be  printed. 

—f  which  causes  the  free  list  to  be  dumped. 

— m  causes  the  entire  coremap  state  to  be  dumped. 

—V  (long  unused)  which  causes  a  hugely  verbose  output  format  to  be  used. 

In  general,  the  output  from  this  program  can  be  confused  by  processes  which  were  forking,  swap¬ 
ping,  or  exiting  or  happened  to  be  in  unusual  states  when  the  crash  occurred.  You  should  exam¬ 
ine  the  flags  fields  of  relevant  processes  in  the  output  of  a  p8tat{S)  to  weed  out  such  processes. 

It  is  possible  to  look  at  the  core  dump  with  adb  if  you  do 

adb  — k  /vmunix  /vmcore 

FILES 

/vmunix  default  system  namelist 

SEE  ALSO 

adb(lS),  ps(l),  crash(8S),  pstat(8) 

AUTHORS 

Ozalp  Babaoglu  and  William  Joy 
DIAGNOSTICS 

Various  diagnostics  about  overlaps  in  swap  mappings,  missing  swap  mappings,  page  table  entries 
inconsistent  with  the  core  map,  incore  pages  which  are  marked  clean  but  differ  from  disk-image 
copies,  pages  which  are  locked  or  intransit,  and  inconsistencies  in  the  free  list. 

It  would  be  nice  if  this  program  analyzed  the  system  in  general,  rather  than  just  the  paging  sys¬ 
tem  in  particular. 
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NAME 

arp  —  address  resolution  display  and  control 

SYNOPSIS 

arp  hostname 

arp  -a  [  vmunix  [  kmem 

arp  -d  hostname 

arp  hostname  ether^addr  \  temp  |  [  pub  | 
arp  -f  filename 

DESCRIPTION 

The  arp  program  displays  and  modifies  the  Internet-to-Ethernet  address  translation  tables  used 
by  the  address  resolution  protocol  (  (irp(4p)). 

With  no  flags,  the  program  displays  the  current  ARP  entry  for  hostname.  With  the  -a  flag,  the 
program  displays  all  of  the  current  ARP  entries  by  reading  the  table  from  the  file  kmem  (default 
/dev/kmem)  based  on  the  kernel  file  vmunix  (default  /vmunix). 

With  the  -d  flag,  a  super-user  may  delete  an  entry  for  the  host  called  hostname. 

The  -B  flag  is  given  to  create  an  ARP  entry  for  the  host  called  hostname  with  the  Ethernet 
address  ether^addr.  The  Ethernet  address  is  given  as  six  hex  bytes  separated  by  colons.  The 
entry  will  be  permanent  unless  the  word  temp  is  given  in  the  command.  If  the  word  pub  is 
given,  the  entry  will  be  "published**,  e.g.,  this  system  will  respond  to  ARP  requests  for  hostname 
even  though  the  hostname  is  not  its  own. 

The  -f  flag  causes  the  file  filename  to  be  read  and  multiple  entries  to  be  set  in  the  ARP  tables. 
Entries  in  the  file  should  be  of  the  form 

hostname  ether_addr  [  temp  |  [  pub  j 
with  argument  meanings  as  given  above. 

SEE  ALSO 

arp(4p),  ifconfig(8c) 


484 


Last  change:  1  February  1985 


Sun  Release  2.0 


CATMAN(8) 


MAINTENANCE  COMMANDS 


CATMAN(8) 


NAME 

catman  —  create  the  cat  files  for  the  manual 
SYNOPSIS 

/usr /etc /cat man  [  — p  |  (  — n  |  [  — w  ]  [  sections  ] 

DESCRIPTION 

Catman  creates  the  preformatted  versions  of  the  on-line  manual  from  the  nroff  input  files.  Each 
manual  page  is  examined  and  those  whose  preformatted  versions  are  missing  or  out  of  date  are 
recreated.  If  any  changes  are  made,  catman  recreates  the  /usr/man/whatls  database. 

If  there  is  one  parameter  not  starting  with  a  it  is  take  to  be  a  list  of  manual  sections  to  look 
in.  For  example 

catman  123 

only  updates  manual  sections  1,  2,  and  3. 

OPTIONS 

— n  Do  not  create  /usr/man/whatls. 

— p  Print  what  would  be  done  instead  of  doing  it. 

— w  Only  create  the  /usr/man/whattB  database.  No  manual  reformatting  is  done. 

FILES 

/usr/man/man?/*.+  raw  (nroff  input)  manual  sections 

/usr/man/cat?/*.*  preformatted  manual  pages 

/usr/lib/makewhatis  commands  to  make  whatis  database 

SEE  ALSO 

man(l) 
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NAME 

chown  —  change  owner 
SYNOPSIS 

/etc/chown  —f  owner  file 
DESCRIPTION 

Chown  changes  the  owner  of  the  files  to  owner.  The  owner  may  be  either  a  decimal  UID  or  a 
login  name  found  in  the  password  file. 

Only  the  super-user  can  change  owner,  in  order  to  simplify  as  yet  unimplemented  accounting  pro¬ 
cedures. 

OPTIONS 

— f  Do  not  report  errors. 

FILES 

/etc/passwd 
SEE  ALSO 

chgrp(l),  chown(2),  passwd(5),  group(5) 
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NAME 

ciri  —  clear  i-node 
SYNOPSIS 

/etc/ciri  filesystem  i-number 
DESCRIPTION 

N.B.:  Clri  is  obsoleted  for  normal  file  system  repair  work  by  /?c<:(8)* 

Clri  writes  zeros  on  the  i-nodes  with  the  decimal  i-numhere  on  the  filesysiem.  After  clri,  any 
blocks  in  the  affected  file  will  show  up  as  ‘missing’  in  an  fcAecfc(8)  of  the  filesystem. 

Read  and  write  permission  is  required  on  the  specified  file  system  device.  The  i-node  becomes 
allocatable. 

The  primary  purpose  of  this  routine  is  to  remove  a  file  which  for  some  reason  appears  in  no 
directory.  If  it  is  used  to  zap  an  i-node  which  does  appear  in  a  directory,  care  should  be  taken  to 
track  down  the  entry  and  remove  it.  Otherwise,  when  the  i-node  is  reallocated  to  some  new  file, 
the  old  entry  will  still  point  to  that  file.  At  that  point  removing  the  old  entry  will  destroy  the 
new  file.  The  new  entry  will  again  point  to  an  unallocated  i-node,  so  the  whole  cycle  is  likely  to 
be  repeated  again  and  again. 

SEE  ALSO 

icheck(8) 

BUGS 

If  the  file  is  open,  clri  is  likely  to  be  ineffective. 
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NAME 

comsat  —  biff  server 

SYNOPSIS 

/usr  /ete/in.comsat 

DESCRIPTION 

Comsat  is  the  server  process  which  listens  for  reports  of  incoming  mail  and  notifies  users  who 
have  requested  to  be  told  when  mail  arrives.  It  is  invoked  as  needed  by  ine(d(8C),  and  times  out 
if  inactive  for  a  few  minutes. 

Comsat  listens  on  a  datagram  port  associated  with  the  “biff”  service  specification  (see  ser- 
t;jces(5))  for  one  line  messages  of  the  form 

user@mail  box-offset 

If  the  user  specified  is  logged  in  to  the  system  and  the  associated  terminal  has  the  owner  execute 
bit  turned  on  (by  a  “biff  y”),  the  offset  is  used  as  a  seek  offset  into  the  appropriate  mailbox  file 
and  the  first  7  lines  or  560  characters  of  the  message  are  printed  on  the  user’s  terminal.  Lines 
which  appear  to  be  part  of  the  message  header  other  than  the  “From”,  “To”,  “Date”,  or  “Sub¬ 
ject”  lines  are  not  printed  when  displaying  the  message. 

FILES 

/etc/utmp  to  find  out  who’s  logged  on  and  on  what  terminals 

SEE  ALSO 

biff(l) 

BUGS 

The  message  header  filtering  is  prone  to  error. 

The  notification  should  appear  in  a  separate  window  so  it  does  not  mess  up  the  screen. 
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NAME 

config  —  build  system  configuration  files 
SYNOPSIS 

/etc/conflg  [  — p  I  config^le 
DESCRIPTION 

Config  does  the  preparation  necessary  for  building  a  new  system  kernel  with  make{l).  The 
config^le  named  on  the  command  line  describes  the  kernel  to  be  made  in  terms  of  options  you 
want  in  your  system,  size  of  tables,  and  device  drivers  to  be  included.  The  format  of  this  file  is 
described  below.  Using  the  — p  option  on  the  command  line  configures  a  system  for  profiling  (see 
kgmon{S)  and  gprof{l)). 

When  you  run  config,  it  uses  several  input  files  located  in  the  conf  subdirectory  of  the  system 
source  (including  your  config^le)  to  generate  the  files  necessary  to  compile  and  link  your  kernel. 
Since  config  places  these  output  files  in  the  directory  named  **/config^le  —  which  it  assumes 
exists  —  you  must  create  this  directory  before  running  config.  One  of  config's  output  files  is  a 
makefile  which  you  use  with  make{l)  to  build  your  system.  For  a  description  of  other  input  and 
output  files,  see  the  FILES  section  below. 

You  use  config  as  follows.  Run  config  from  the  con/ subdirectory  of  the  system  source  (in  a  typi¬ 
cal  Sun  environment,  from  /sye/conf): 

tutorial#  /etc/conflg  config^le 
Don't  forget  to  run  make  depend 
tutorial# 

While  config  is  running  watch  for  any  errors.  Never  use  a  kerne!  which  config  has  complained 
about;  the  results  are  unpredictable.  If  config  completes  successfully,  you  can  change  directory 
to  the  n^/config^le  directory,  where  it  has  placed  the  new  makefile,  and  use  make  to  create  the 
dependency  graph  for  the  new  system: 

Don't  forget  to  run  make  depend 
tutorial#  cd  config^le 
tutorial#  make  depend 
,,,lot$  of  output,,, 
tutorial#  make 
,,,lot8  more  output,,. 

Then  you  can  install  your  new  kerne!  and  try  it  out, 

CONFIG  FILE  FORMAT 

In  the  following  descriptions,  a  number  can  be  a  decimal  integer,  a  whole  octal  number  or  a 
whole  hexadecimal  number.  Hex  and  octal  are  specified  to  config  in  the  same  way  they  are 
specified  to  the  C  compiler,  a  number  starting  with  "Ox**  is  a  hex  number  and  a  number  starting 
with  just  a  "O"  is  an  octal  number.  When  specifying  the  timezone,  you  may  also  use  floating 
point  numbers. 

Comments  are  specified  in  a  config  file  with  the  character  All  characters  from  a  to  the 
end  of  a  line  are  ignored. 

Lines  beginning  with  tabs  are  considered  continuations  of  the  previous  line. 

Lines  of  the  configuration  file  can  be  one  of  two  basic  types.  First,  there  are  lines  which  describe 
general  things  about  your  system: 

machine  type 

This  is  system  is  to  run  on  the  machine  type  specified.  Only  one  machine  type  can  appear 
in  the  config  file.  The  legal  type  for  a  Sun  system  is  sun. 
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cpu  "type’ 

This  system  is  to  run  on  the  cpu  type  specified.  For  a  Sun  system,  "type"  is  "SUN2"  (note 
that  the  double  quotes  are  part  of  the  designation). 

Ident  name 

Gives  the  system  identifier  —  a  name  for  the  machine  or  machines  that  run  this  kernel. 
name  must  be  enclosed  in  double  quotes  if  it  contains  both  letters  and  numbers  (for  exam¬ 
ple,  "SDST120"),  or  you  will  get  a  syntax  error  when  you  run  jetcfconfig.  Also,  note  that 
if  name  is  GENERIC,  you  can  specify  the  unique  config_clau8e  swap  generic  in  the 
conflg  line  described  below  (see  the  next  section,  Specific  System  Description  Lines).  If 
you  use  any  other  string  for  name,  and  you  also  include  an  options  GENERIC  line,  you 
can  still  use  the  swap  generic  line.  However,  if  you  use  any  other  string  for  name  and 
omit  the  options  GENERIC  line,  you  may  NOT  use  the  line  conflg  vmunlx  swap  gen¬ 
eric  to  specify  your  kernel  image. 

timesone  number  [  dst  | 

Specifies  the  timezone  you  are  in,  measured  in  the  number  of  hours  west  of  GMT.  5  is 
EST,  8  is  PST.  Negative  numbers  indicate  hours  east  of  GMT.  If  you  specify  dst,  the  sys¬ 
tem  will  convert  to  and  from  daylight  savings  time  when  appropriate. 

maxusers  number 

The  maximum  expected  number  of  simultaneously  active  user  on  this  system  is  number. 
This  number  is  used  to  size  several  system  data  structures. 

options  optlist 

Compile  the  listed  options  into  the  system.  Options  in  this  list  are  separated  by  commas. 
There  is  a  list  of  options  that  you  may  specify  in  the  generic  makefile.  A  line  of  the  form 
"options  FUNNY,HAHA"  yields  -DFUNNY  -DHAHA  to  the  C  compiler.  An  option  may 
be  given  a  value,  by  following  its  name  with  "="  then  the  value  enclosed  in  (double)  quotes. 
None  of  the  standard  options  use  such  a  value. 

conflg  sysname  config^ciauses... 

Generate  a  system  with  name  sysname  and  configuration  as  specified  in  config-clauses. 
The  sysname  is  used  to  name  the  resultant  binary  image  and  per-system  swap  configuration 
files.  The  config-clauses  indicate  the  location  for  the  root  file  system,  one  or  more  disk 
partitions  for  swapping  and  paging,  and  a  disk  partition  to  which  system  dumps  should  be 
made.  All  but  the  root  device  specification  may  be  omitted;  config  will  assign  default 
values  as  described  below. 

root  A  root  device  specification  is  of  the  form  root  on  zyOd.  If  a  specific  partition  is 
omitted  —  for  example,  if  only  root  on  xyO  is  specified  —  the  “a”  partition  is 
assumed.  When  a  generic  system  is  being  built,  no  root  specification  should  be 
given;  the  root  device  will  be  defined  at  boot  time  by  prompting  the  console. 

swap  Swap  device  specifications  have  two  possible  forms.  If  a  generic  swap  configuration 
is  required,  the  clause  swap  generic  should  be  specifed.  Otherwise,  if  a  single  par¬ 
tition  is  to  be  used  for  swapping,  one  may  specify  swap  on  zyOb.  If  multiple  parti¬ 
tions  are  to  be  interleaved  one  should  specify  something  of  the  form  swap  on  zyO 
and  xyl  and  zylg.  If  no  swap  specification  is  given,  config  assumes  swapping 
should  be  done  on  the  “b”  partition  of  the  root  device.  Swapping  areas  may  be 
almost  any  size  and  multiple  swap  partitions  of  varying  size  may  be  interleaved. 
Partitions  used  for  swapping  are  sized  at  boot  time  by  the  system;  to  override 
dynamic  sizing  of  a  swap  area  the  number  of  sectors  in  the  swap  area  can  be 
specified  in  the  config  file.  For  example,  iwap  on  zyOb  size  99999  would  configure 
a  swap  partition  with  99999  sectors. 

dumps  The  location  to  which  system  dumps  are  sent  may  be  specified  with  a  clause  of  the 
form  dumps  on  zyl.  If  no  dump  device  is  specified,  the  first  swap  partition 
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specified  is  used.  If  a  device  is  specified  without  a  particular  partition,  the  “b”  par¬ 
tition  is  assumed.  If  a  generic  configuration  is  to  be  built,  no  dump  device  should 
be  specified;  the  dump  device  will  be  assigned  to  the  swap  device  dynamically 
configured  at  boot  time. 

Dumps  are  placed  at  the  end  of  the  partition  specified.  Their  size  and  location  is 
recorded  in  global  kernel  variables  dumpeize  and  dumploy  respectively,  for  use  by 
8avecore{^). 

Device  names  specified  in  configuration  clauses  are  mapped  to  block  device  major  numbers 
with  the  file  device9,machine,  where  machine  is  the  machine  type  previously  specified  in  the 
configuration  file.  If  a  device  name  to  block  device  major  number  mapping  must  be  over¬ 
ridden,  a  device  specification  may  be  given  in  the  form  m^or  x  minor  y. 

The  second  group  of  lines  in  the  configuration  file  describe  which  devices  your  system  has  and 
what  they  are  connected  to  (for  example,  I  have  aXylogics  450  Disk  Controller  on  the  main  bus). 
These  lines  have  the  following  format: 

dev^type  dev^name  at  con^dev  more_info 

Dev^type  is  either  tapCi  disk^  controller p  devlccp  or  pseudo^devlce.  These  types  have  the  fol¬ 
lowing  meanings: 

controller 

is  a  disk  or  tape  controller. 

disk  or  tape 

are  devices  connected  to  a  controller. 

device 

is  something  ‘attached’  to  the  main  system  bus,  like  a  cartridge  tape  interface. 

pseudo-device 

A  software  subsystem  or  driver  treated  like  a  device  driver,  but  without  any  associ¬ 
ated  hardware.  Current  examples  are  the  pseudo-tty  driver  and  various  network 
subsystems.  (For  pseudo-devices,  moreJInfo  may  be  specified  as  an  integer,  that 
gives  the  value  of  the  symbol  defined  in  the  header  file  created  for  that  device,  and 
is  generally  used  to  indicate  the  number  of  instances  of  the  pseudo-device  to  create. 
If  you  load  a  subsystem  you  will  probably  find  it  convenient  to  enable  conditional 
code  using  an  options  specification. 

Dev^name  is  the  standard  UNIX  device  name  and  unit  number  (if  the  device  is  not  a  psuedo- 
devlce)  of  the  device  you  are  specifying.  For  example,  xycO  is  the  dev^name  for  the  first  Xylo- 
gics  controller  in  a  system;  arO  names  the  first  quarter-inch  tape  controller. 

Con^dev  is  what  the  device  you  are  specifying  is  connected  to.  For  example,  disk  xyl  is  con¬ 
nected  to  controller  xycO. 

More^info  is  a  sequence  of  the  following: 

car  (  bus^spec  space^spec  [  addr 

Specifies  the  address  of  the  csr  (command  and  status  registers)  for  a  device.  The 
optional  bus  specification  {bu9^$pec)  and  space  specification  {space^spec)  pair  may 
be  included  in  the  address;  otherwise,  config  will  use  a  heuristic  using  addr  to 
determine  the  bus  and  space.  Typically,  addr  is  given  as  a  hexidecimal  value. 

bus^spec  may  be: 

all  The  device  is  on  any  main  system  bus. 

mb  The  device  is  on  the  Multibus, 

vme  The  device  is  on  the  VMEbus. 


Sun  Release  2.0 


Last  change:  1  February  1085 


491 


CONFIG  (8) 


MAINTENANCE  COMMANDS 


CONFIG  (8) 


spact^sptc  may  be: 

vlrt  Virtual  address  (preset  by  monitor)  follows, 

obmem  The  following  address  is  in  on-board  memory, 

oblo  The  following  address  is  in  on-board  I/O. 

busmem  The  following  address  is  in  main  bus  memory, 

busio  The  following  address  is  in  main  bus  I/O. 

The  csr  address  must  be  specified  for  all  controllers,  and  for  all  devices  connected  to  the 
main  system  bus  (whether  it  is  a  Multibus  or  a  VMEbus). 

drive  number 

For  a  disk  or  tape,  specifies  which  drive  this  is. 
flags  number 

These  flags  are  made  available  to  the  device  driver,  and  are  usually  read  at  system 
initialization  time. 

priority  level 

For  devices  which  interrupt,  specifies  the  interrupt  level  at  which  the  device 
operates. 

vector  intr  number  [  intr  number  .  .  .  | 

For  devices  which  use  vectored  interrupts  on  VMEbus  systems,  intr  specifies  the 
vectored  interrupt  routine  and  number  the  corresponding  vector  to  be  used  (64- 
255). 

A  T  may  be  substituted  for  a  number  in  two  places  and  the  system  will  figure  out  what  to  fill  in 
for  the  ?  when  it  boots.  You  can  put  question  marks  on  a  con^dev  (for  example,  at  xyc?),  or  on  a 
drive  number  (for  example,  drive  ?).  This  allows  redundancy,  as  a  single  system  can  be  built 
which  will  boot  on  different  hardware  configurations. 

The  easiest  way  to  understand  config  files  it  to  look  at  a  working  one  and  modify  it  to  suit  your 
system.  Good  examples  are  provided  in  the  Configuring  the  System  Kernel  chapter  and  second 
appendix  of  the  Installing  UNIX  on  the  Sun  Workstation  manual. 

FILES 

Files  in  /sys/conf  which  may  be  useful  for  developing  the  config^le  used  by  config  are: 

GENERIC  Generic  configuration  file  for  Sun  systems,  containing  all 
possible  device  description  lines 
README  File  describing  how  to  make  a  new  kernel 

As  shipped  from  Sun,  the  files  used  by  /etc/ config  as  input  are  in  the  /sys/conf  directory; 

config^le  System-specific  configuration  file 

makefile.sun  Generic  prototype  makefile  for  Sun  systems 

files  List  of  common  files  required  to  build  a  basic  kernel 

files.sun  List  of  files  for  a  Sun-specific  kernel 

devices.sun  Name  to  major  device  mapping  file  for  Sun  systems 

/etc/ config  places  its  output  files  in  the  *./ config^le  directory: 

mbglue.s  Short  assembly  language  routines  used  for  vectored  interrupts 

ioconf.c  Describes  I/O  devices  attached  to  the  system 

makefile  Used  with  make{\)  to  build  the  system 

devic€^name}i  A  set  of  header  files  (various  devicejname^s)  containing  devices 
which  can  be  compiled  into  the  system. 

SEE  ALSO 

The  SYNOPSIS  portion  of  each  device  entry  in  the  Section  4  pages  of  the  System  Interface 
Manual, 

In  the  Installing  UNIX  on  the  Sun  Workstation  Manual,  see  the  Configuring  the  System  Kernel 
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chapter,  and  the  Sample  Configuration  FUe$  appendix. 

The  line  numbers  reported  in  error  messages  are  usually  off  by  one. 
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NAME 

crash  —  what  happens  when  the  system  crashes 
DESCRIPTION 

This  section  explains  what  happens  when  the  system  crashes  and  how  you  can  analyze  crash 
dumps. 

When  the  system  crashes  voluntarily  It  displays  a  message  of  the  form 
panic:  why  i  gave  up  the  ghost 

on  the  console,  takes  a  dump  on  a  mass  storage  peripheral,  and  then  invokes  an  automatic  reboot 
procedure  as  described  in  reboot{S),  Unless  some  unexpected  inconsistency  is  encountered  in  the 
state  of  the  file  systems  due  to  hardware  or  software  failure  the  system  will  then  resume  multi¬ 
user  operations. 

The  system  has  a  large  number  of  internal  consistency  checks;  if  one  of  these  fails,  it  will  panic 
with  a  very  short  message  indicating  which  one  failed. 

The  most  common  cause  of  system  failures  is  hardware  failure,  which  can  reflect  itself  in  different 
ways.  Here  are  the  messages  which  you  are  likely  to  encounter,  with  some  hints  as  to  causes. 
Left  unstated  in  all  cases  is  the  possibility  that  hardware  or  software  error  produced  the  message 
in  some  unexpected  way. 

lO  err  In  puah 
hard  lO  err  In  swap 

The  system  encountered  an  error  trying  to  write  to  the  paging  device  or  an  error  in  read¬ 
ing  critical  information  from  a  disk  drive.  You  should  fix  your  disk  if  it  is  broken  or 
unreliable. 

timeout  table  overflow 

This  really  shouldn’t  be  a  panic,  but  until  we  fix  up  the  data  structure  involved,  running 
out  of  entries  causes  a  crash.  If  this  happens,  you  should  make  the  timeout  table  bigger 
by  changing  the  value  of  ncatlout  in  the  param^c  file,  and  then  rebuild  your  system. 

trap  type  type,  pld  process-idf  pc  «=  program- counteff  »r  «  etatus-registerf  context  context- 
number 

A  unexpected  trap  has  occurred  within  the  system;  typical  trap  types  are: 

•  Bus  error 

•  Address  error 

•  Illegal  instruction 

•  Divide  by  zero 

•  Chk  instruction 

•  Trapv  instruction 

•  Privilege  violation 

•  Trace 

•  1010  emulator  trap 

•  1111  emulator  trap 

•  Stack  format  error 

•  Unitialized  interrupt 

•  Spurious  interrupt 

The  favorite  trap  types  in  system  crashes  are  *Bus  error’  or  ‘Address  error’,  indicating  a 
wild  reference.  The  proceso-id  is  the  id  of  the  process  running  at  the  time  of  the  fault, 
program-counter  is  the  hexadecimal  value  of  the  program  counter,  8tatu9-regi$ter  is  the 
hexadecimal  value  of  the  status  register,  and  context-number  is  the  context  that  the  pro¬ 
cess  was  running  in.  These  problems  tend  to  be  easy  to  track  down  if  they  are  kernel 
bugs  since  the  processor  stops  cold,  but  random  fiakiness  seems  to  cause  this  sometimes. 

Init  died 
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The  system  initialization  process  has  exited.  This  is  bad  news,  as  no  new  users  will  then 
be  able  to  log  in.  Rebooting  is  the  only  fix,  so  the  system  just  does  it  right  away. 

That  completes  the  list  of  panic  types  you  are  likely  to  see. 

When  the  system  crashes  it  writes  (or  at  least  attempts  to  write)  an  image  of  memory  into  the 
back  end  of  the  primary  swap  area.  After  the  system  is  rebooted,  the  program  saveeore{S)  runs 
and  preserves  a  copy  of  this  core  image  and  the  current  system  in  a  specified  directory  for  later 
perusal.  See  savecore(8)  for  details. 

To  analyze  a  dump  you  should  begin  by  running  adi(lS)  with  the  — k  flag  on  the  core  dump.  A 
more  complete  discussion  of  system  debugging  is  impossible  here.  See,  however,  ‘Using  ADB  to 
Debug  the  UNIX  Kernel’. 

SEE  ALSO 

adb(lS},  analyze(8),  reboot(8) 

Using  ADB  to  Debug  the  UNIX  Kernel,  in  the  System  Internals  for  the  Sun  Workstation 
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NAME 

cron  —  clock  daemon 

SYNOPSIS 

/etc/cron 

DESCRIPTION 

Cron  executes  commands  at  specified  dates  and  times  according  to  the  instructions  in  the  file 
/usr/lib/crontah.  Since  cron  never  exits,  it  should  only  be  executed  once.  This  is  best  done  by 
running  cron  from  the  initialization  process  through  the  file  /etc/rc;  see  tnt^(8). 

/usr/lib/croniab  consists  of  lines  of  six  fields  each.  The  fields  are  separated  by  spaces  or  tabs. 
The  first  five  are  integer  patterns  to  specify  the  minute  (0-59),  hour  (0-23),  day  of  the  month  (1- 
31),  month  of  the  year  (1-12),  and  day  of  the  week  (1-7  with  l«Monday).  Each  of  these  patterns 
may  contain  a  number  in  the  range  above;  two  numbers  separated  by“a  dash  meaning  a  range 
inclusive;  a  list  of  numbers  separated  by  commas  meaning  any  of  the  numbers;  or  an  asterisk 
meaning  all  legal  values.  The  sixth  field  is  a  string  that  is  executed  by  the  shell  at  the  specified 
times.  A  percent  character  in  this  field  is  translated  to  a  new-line  character.  Only  the  first  line 
(up  to  a  %  or  end  of  line)  of  the  command  field  is  executed  by  the  shell.  The  other  lines  are 
made  available  to  the  command  as  standard  input. 

Here  are  a  few  example  lines  from  /usr/lib/crontah,  to  give  you  a  better  sense  of  the  file’s  for¬ 
mat: 

0  0***  calendar  - 

15  0  *  *  *  /usr/etc/sa  -s  >/dev/null 

0,30  *  *  *  ♦  /etc/dmesg  -  »/usr/ad m/messages 

4  *  *  *  find  /usr/preserve  -mtime  4-7  -a  -exec  rm  -f  {}  ; 

10  4  *  *  *  egrep  ’SYSERRlrefusedjunreachable’  /usr/spool/log/syslog.O  [mail  Postmaster 

Cron  examines  fnsrflibfcrontab  under  the  following  conditions: 

•  At  least  once  per  hour  (on  the  hour). 

•  When  the  next  command  is  to  be  run  —  cron  looks  ahead  until  the  next  command  and  sleeps 
until  then. 

•  When  cron’s  process  is  sent  a  SIGHUP.  This  means  that  comeone  who  changes 
I  usr/lib/croniab  can  get  cron  to  look  at  it  right  away. 

You  can  also  create  the  /usr/ adm/ cronlog  file,  if  you  wish.  If  the  file  exists,  cron  logs  to  it  each 
time  it  executes  an  instruction  from  /usr/lib/croniab.  You  can  thus  use  the  cronlog  file  to  make 
sure  cron  is  running  properly.  The  lines  in  the  file  consist  of  a  timestamp,  and  process  statement. 
Lines  look  something  like  this: 

Thu  Mar  8  10:20:00  1984:  /etc/dmesg  -  »/usr/adm/messages 
Thu  Mar  8  10:29:59  1984:  /etc/atrun 

Thu  Mar  8  10:30:00  1984:  /etc/dmesg  -  »/usr/adm/messages 
Thu  Mar  8  10:39:59  1984:  /etc/dmesg  -  »/usr/ad m/messages 

FILES 

/usr/lib/crontab  Instruction  file 

/usr/adm/cronlog  Log  file 

SEE  ALSO 

crontab(5) 
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NAME 

dcheck  —  file  system  directory  consistency  check 
SYNOPSIS 

/usr /etc /dcheck  (  —1  numbers  ]  (  filesystem  [ 

DESCRIPTION 

N.B.s  Dcheck  is  obsoleted  for  normal  consistency  checking  by  f8ck{S). 

Dcheck  reads  the  directories  in  a  file  system  and  compares  the  link-count  in  each  inode  with  the 
number  of  directory  entries  by  which  it  is  referenced*  If  the  file  system  is  not  specified,  dcheck 
checks  a  set  of  default  file  systems. 

Dcheck  is  fastest  if  the  raw  version  of  the  special  file  is  used,  since  the  i-!ist  is  read  in  large 
chunks. 

OPTIONS 

—I  numbers 

Numbers  is  a  list  of  i-numbers;  when  one  of  those  i-numbers  turns  up  in  a  directory,  the 
number,  the  i-number  of  the  directory,  and  the  name  of  the  entry  are  reported. 

FILES 

Default  file  systems  vary  with  installation. 

SEE  ALSO 

fsck(8),  icheck(8),  fs(5),  clri(8),  ncheck(8) 

DIAGNOSTICS 

When  a  file  turns  up  for  which  the  link-count  and  the  number  of  directory  entries  disagree,  the 
relevant  facts  are  reported.  Allocated  files  which  have  0  link-count  and  no  entries  are  also  listed. 
The  only  dangerous  situation  occurs  when  there  are  more  entries  than  links;  if  entries  are 
removed,  so  the  link-count  drops  to  0,  the  remaining  entries  point  to  thin  air.  They  should  be 
removed.  When  there  are  more  links  than  entries,  or  there  is  an  allocated  file  with  neither  links 
nor  entries,  some  disk  space  may  be  lost  but  the  situation  will  not  degenerate. 

BUGS 

Since  dcheck  is  inherently  two-pass  in  nature,  extraneous  diagnostics  may  be  produced  if  applied 
to  active  file  systems. 

Dcheck  is  obsoleted  by  fsck  and  remains  for  historical  reasons. 

Inode  numbers  less  than  2  are  invalid. 
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NAME 

diag  —  stand-alone  disk  initialization  and  diagnosis 


SYNOPSIS 

>b  stand/diag 


DESCRIPTION 

Diag  is  a  general  purpose  stand-alone  package  for  initializing,  diagnosing,  and  repairing  disks.  It 
supports  the  various  SMD  and  ST-506  disk  controllers. 

Note:  Diag  is  not  a  system  utility  and  can  only  be  called  from  the  Sun  Workstation  PROM  moni¬ 
tor. 

The  most  common  use  of  diag  is  formatting  and  labelling  a  disk  —  see  the  formatt  lab  elf  and  par¬ 
tition  commands. 

Immediately  after  startup,  diag  prompts  for  information  about  the  particular  disk  drive(s)  and 
controller(s)  it  is  to  work  with.  There  is  a  facility  for  specifying  additional  information  about  non¬ 
standard  disks. 


Diag  tries  to  access  the  disk  controller  you  have  defined.  If  the  attempt  succeeds,  it  gives  you  a 
status  report  on  the  disk  and  issues  the  ‘diag>^  prompt.  If  the  attempt  fails  (if  the  controller  is 
ill-defined  or  nonexistent),  you  get  a  bus  error  message,  and  return  to  the  PROM  monitor. 

Once  configured,  diag  accepts  the  comands  listed  below.  Only  enough  characters  to  uniquely 
identify  the  command  need  be  typed. 

abortdma  Aborts/does  not  abort  the  dmatest  command  when  a  data  miscompare  is  detected. 

That  is,  if  the  interna!  variable  set  by  abortdma  is  ‘on’  (default),  the  dmatest  com¬ 
mand  aborts  as  soon  as  it  finds  an  error;  otherwise,  the  dmatest  continues. 

clear  Sends  a  restore  command  to  a  disk.  This  is  needed  to  manually  reset  disk  faults. 


dtag 

dmatest 


errors 

fix 


format 

help  or  r 
info 

label 

map 


Re-initializes  the  diag  program  itself  —  goes  back  to  phase  one  of  the  initialization 
process  described  above. 

Begins  a  continuous  DMA  test.  The  test  copies  random  data  to  and  from  the  desig¬ 
nated  controller,  comparing  data.  If  a  miscompare  is  found,  an  error  message  is 
displayed  and  the  test  aborts  (unless  the  abortdma  command  is  used  —  see 
aboridmOf  above).  Note:  this  command  is  available  only  with  the  Xylogics  450 
Controller, 

Reports/does  not  report  all  errors  as  they  occur  (toggles;  default  is  reporting  off). 

Formats  and  verifies  a  range  of  tracks;  any  defective  tracks/sectors  found  are 
automatically  corrected  using  mapping  or  slipping.  Note;  this  command  is  avail¬ 
able  for  SMD  controllers  only. 

For  SMD  disks,  formats  the  entire  disk;  for  SCSI  disks,  initiates  the  SCSI  format 
program. 

Displays  a  list  of  the  available  commands. 

Reports/suppresses  report  of  all  disk  activity  as  it  completes  (toggles;  default  is 
reporting  off). 

Labels  the  disk. 

Displays  current  mappings  and  allows  you  to  explicitly  map  one  track/sector  to  a 
different  track/sector.  Usually  used  for  manual  bad  sector  mapping.  The  format 
and  fix  commands  usually  do  this  automatically  when  a  bad  track/sector  is  found. 
Note:  the  map  command  is  disk  controller-dependent:  you  can  map  tracks  with  an 
Interphase  controller,  and  sectors  with  Xylogics  controllers.  This  command  is  not 
available  for  use  with  Adaptec  disk  controllers  (ST-506  interface). 
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Q 


mapcheck 


partition 


position 

quit 

rhdr 

read 


scan 


seek 

slip 

slipmsgs 

status 

test 

time 

translate 

verify 

version 

whdr 


Enables/disables  checking  for  overlapping  mapped  sectors/tracks  during  the  posi- 
tioriy  read,  test,  or  write  commands.  If  the  internal  variable  set  by  mapcheck  is  ‘on’ 
when  an  error  occurs  (default),  then  the  current  mappings  (if  any)  are  read  from 
the  disk  and  checked  to  see  if  there  are  overlapping  mappings  over  the  area  of  the 
disk  where  the  transfer  failed. 

Creates,  assigns,  or  modifies  logical  partition  tables  for  a  disk.  The  UNIX  operating 
system  requires  logical  partitions.  The  label  command  writes  the  partition  map  to 
the  disk.  There  are  standard  partition  tables  for  each  type  of  disk  that  diag  knows 
about. 

Continuously  tests  the  disk  by  reading  random  sectors  from  the  disk.  To  abort  the 
test,  type  a  "C  (CONTROL-C). 

Quits  from  diag  and  returns  to  the  PROM  monitor. 

Reads  and  displays  the  track  headers  for  a  specified  track.  Note:  this  command  is 
available  for  the  Xylogics  450  controller  only. 

Reads  specified  blocks  from  the  disk.  The  read  command  prompts  for  the  starting 
block  number,  number  of  blocks,  and  the  block  increment.  The  read  command 
doesn’t  report  the  data  it  reads  —  it  is  intended  for  verifying  that  blocks  are  read¬ 
able. 

Continuously  scans  over  a  range  of  sectors  looking  for  defective  sectors  by 
writing/reading/verifying  various  bit  patterns  to  sequential  sectors.  Any  data  on 
the  disk  in  the  range  to  be  scanned  is  destroyed.  Sectors  previously  mapped  are  not 
scanned,  so  any  errors  reported  will  be  newly  found  defective  sectors.  If  used  with 
a  Xylogics  controller,  defective  sectors  can  be  automatically  mapped/slipped  when 
they  are  found.  To  abort  the  scan,  type  a  *C  (CONTROL-C). 

Performs  a  seek  test  on  the  disk:  a  seek  is  made  to  every  cylinder  and  to  every  pos¬ 
sible  cylinder  distance. 

Explicitly  slips  one  sector  on  a  track.  Usually  used  for  manual  bad  sector  slipping. 
The  format  and  fix  commands  usually  do  this  automatically  when  bad  sectors  are 
found  and  the  proper  conditions  exist.  Note:  slipping  is  available  only  with  the 
Xylogics  450  controller,  and  only  when  the  disk  has  a  spare  data  sector  per  track. 

Displays/suppresses  display  of  track  headers  before  and  after  each  slip  operation 
that  occurs  during  the  fix,  format,  and  slip  commands  (toggles;  default  is  display 
off). 

Reports  the  ready  status  of  each  drive  on  the  current  controller. 

Continuously  tests  the  disk  by  writing  random  data  to  random  sectors  on  the  disk 
and  then  verifying  that  the  correct  data  can  be  read  back.  The  test  command  des¬ 
troys  data  on  the  disk.  To  abort  the  test,  type  a  (CONTROL-C). 

Turns  timing  on/off.  When  timing  is  on,  diag  reports  on  how  long  certain  opera¬ 
tions  take  —  diag  is  less  verbose  in  this  state  so  it  doesn’t  waste  time  displaying 
messages  (toggles;  default  is  timing  off). 

Translates  a  given  block  number  into  its  decimal  value,  hexadecimal  value,  and  log¬ 
ical  disk  address. 

Reads  and  displays  the  label  from  the  disk.  Shows  the  logical  partition  assign¬ 
ments.  This  done  automatically  when  the  /a6e/  command  has  labelled  the  disk. 

Displays  the  SCCS  identification  strings  for  this  version  of  diag. 

Modifies  and  writes  the  track  headers  for  a  specified  track.  Note:  this  command 
is  available  with  the  Xylogics  450  controller  only.  Also,  it  should  be  used  only  for 
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specialized  patching  —  misuse  may  destroy  track  data. 

write  Verifies  that  blocks  are  writable  by  writing  garbage  data  to  specified  blocks  on  the 

disk.  The  write  command  prompts  for  the  starting  block  number,  number  of 
blocks,  and  the  block  increment. 

+  Adds  two  block  numbers  and  reports  the  result  in  decimal,  hexadecimal,  and  as  a 

logical  disk  address. 

—  Subtracts  two  block  numbers  and  reports  the  result  in  decimal,  hexadecimal,  and  as 

a  logical  disk  address. 

Block  numbers  may  be  entered  either  as  an  absolute  decimal  block  number,  or  as  a  disk  address 

of  the  form  cylinder/head/sector. 

Any  diag  command  may  be  aborted  by  typing  a  (CONTROL-C). 
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NAME 

dkinfo  —  report  information  about  a  disk’s  geometry  and  partitioning 
SYNOPSIS 

/ete/dkinfo  di8k\partit%on\ 

DESCRIPTION 

Dkinfo  gives  the  total  number  of  cylinders,  heads,  and  sectors  or  tracks  on  the  specified  disk,  and 
gives  this  information  along  with  the  starting  cylinder  for  the  specified  partition.  If  no  partition 
is  specified  on  the  command  line,  dkinfo  reports  on  all  partitions. 

The  disk  specification  here  is  a  disk  name  of  the  form  xxn,  where  xx  is  the  controller  device 
abbreviation  (ip,  xy,  etc.)  and  n  is  the  disk  number.  The  partition  specification  is  simply  the 
letter  used  to  identify  that  partition  in  the  standard  UNIX  nomenclature.  For  example, 
7etc/dkinfo  xyO’  reports  on  the  first  disk  in  a  system  controlled  by  a  Xylogics  controller; 
7etc/dkinfo  xyOg'  reports  on  the  seventh  partition  of  such  a  disk. 

You  must  be  be  able  to  open  fdevfrxxnp  to  run  dkinfo.  Usually,  only  the  superuser  can  do  so. 
EXAMPLE 

A  request  for  information  on  my  local  disk,  an  84  MByte  disk  controlled  by  a  Xylogics  450  con¬ 
troller,  might  look  like  this: 

#  /etc/dklnfo  xyO 

xyO:  Xylogics  450  controller  at  addr  ee40,  unit  #  0 
586  cylinders  7  heads  32  sectors/track 
a:  15884  sectors  (70  cyls,  6  tracks,  12  sectors) 
starting  cylinder  0 
b:  33440  sectors  (149  cyls,  2  tracks) 
starting  cylinder  71 
c:  131264  sectors  (586  cyls) 
starting  cylinder  0 
d:  No  such  device  or  address 
e:  No  such  device  or  address 
f:  No  such  device  or  address 
g:  81760  sectors  (365  cyls) 
starting  cylinder  221 
h:  No  such  device  or  address 

# 

SEE  ALSO 

dk(4),  diag(8) 
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NAME 

dmesg  —  collect  system  diagnostic  messages  to  form  error  log 
SYNOPSIS 

/usr/etc/dmeBg  |  -  ] 

DESCRIPTION 

Dmesg  looks  in  a  system  buffer  for  recently  printed  diagnostic  messages  and  prints  them  on  the 
standard  output.  The  messages  are  those  printed  by  the  system  when  device  (hardware)  errors 
occur  and  (occasionally)  when  system  tables  overflow  non-fatally.  If  the  flag  is  given,  then 
dmesg  computes  (incrementally)  the  new  messages  since  the  last  time  it  was  run  and  places  these 
on  the  standard  output.  This  is  typically  used  with  cron{8)  to  produce  the  error  log 
/usrfadm/ messages  by  running  the  command 
/etc/dmesg  -  »  /usr/adm/messages 
every  10  minutes. 

FILES 

/usr/adm/messages  error  log  (conventional  location) 

/usr/adm/msgbuf  scratch  file  for  memory  of  —  option 

BUGS 

The  system  error  message  buffer  is  of  small  finite  size.  As  dmesg  is  run  only  every  few  minutes, 
not  all  error  messages  are  guaranteed  to  be  logged.  This  can  be  construed  as  a  blessing  rather 
than  a  curse. 

Error  diagnostics  generated  immediately  before  a  system  crash  will  never  get  logged. 
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NAME 

dump  —  incremental  file  system  dump 
SYNOPSIS 

/etc/dump  [  key  [  argument  ...  [  |  filesystem 
DESCRIPTION 

Dump  copies  to  magnetic  tape  all  files  changed  after  a  certain  date  in  the  filesystem.  The  key 
specifies  the  date  and  other  options  about  the  dump.  Key  consists  of  characters  from  the  set  0- 
9|b|c! 

0—0  This  number  is  the  ‘dump  level’.  All  files  modified  since  the  last  date  stored  in  the  file 
/etc/ dump  dates  for  the  same  filesystem  at  lesser  levels  will  be  dumped.  If  no  date  is  deter- 
mined  by  the  level,  the  beginning  of  time  is  assumed;  thus  the  entire  filesystem  is  dumped  if 
the  0  option  is  used. 

b  Specifies  the  blocking  factor  for  the  dump.  The  blocking  factor  is  taken  from  the  next 
argument  on  the  command  line.  The  default  blocking  factor  is  10. 

c  Dump  to  cartridge  tape  instead  of  standard  half-inch  magnetic  tape. 

d  The  density  of  the  tape,  expressed  in  BPI,  is  taken  from  the  next  argument.  This  is  used  in 
calculating  the  amount  of  tape  used  per  reel.  The  default  is  1600. 

f  Place  the  dump  on  the  next  argument  file  instead  of  the  tape.  If  file  is  of  the  form 
machine:device,  dump  to  a  remote  machine.  If  argument  is  dump  to  standard  output. 
If  dump  is  called  as  rdump,  the  tape  defaults  to  dumpho8t:/det;/ otherwise^  the 
tape  defaults  to  /dev/rmt8.  Use  an  alias  for  dumphost  in  the  file  /etc/hosts  to  direct 
the  output  to  a  desired  remote  machine. 

n  Whenever  dump  requires  operator  attention,  notify  by  means  similar  to  a  tyaW(l)  all  of  the 
operators  in  the  group  “operator”. 

8  The  size  of  the  dump  tape  is  specified  in  feet.  The  number  of  feet  is  taken  from  the  next 
argument.  When  the  specified  size  is  reached,  dump  waits  for  reels  to  be  changed.  The 
default  tape  size  is  2300  feet. 

u  If  the  dump  completes  successfully,  write  the  date  of  the  beginning  of  the  dump  on  file 
/  etc/  dump  dates.  This  file  records  a  separate  date  for  each  filesystem  and  each  dump  level. 
The  format  of  /  etc/  dump  dates  is  readable  by  people,  consisting  of  one  free  format  record 
per  line:  filesystem  name,  increment  level  and  ctime(S)  format  dump  date.  /  etc/  dump  dates 
may  be  edited  to  change  any  of  the  fields,  if  necessary. 

w  Dump  tells  the  operator  of  filesystems  which  need  to  be  dumped.  The  information  is 
gleaned  from  the  files  /etc/dumpdates  and  /etc/ /stab.  If  the  w  option  is  set,  all  other 
options  are  ignored,  and  dump  exits  immediately. 

W  Like  the  w,  but  the  W  option  causes  dump  to  print  out,  for  each  file  system  in 
/etc/dumpdates  the  most  recent  dump  date  and  level,  and  highlights  those  file  systems  that 
should  be  dumped.  < 

If  no  arguments  are  given,  the  key  is  assumed  to  be  Ou. 

Dump  requires  operator  intervention  on  these  conditions:  end  of  tape,  end  of  dump,  tape  write 
error,  tape  open  error  or  disk  read  error  (if  there  are  more  than  a  threshold  of  32).  In  addition 
to  alerting  all  operators  implied  by  the  n  key,  dump  interacts  with  the  operator  on  dump^s  con¬ 
trol  terminal  at  times  when  dump  can  no  longer  proceed,  or  if  something  is  grossly  wrong.  All 
questions  dump  poses  must  be  answered  by  typing  “yes”  or  “no”,  appropriately. 

Since  making  a  dump  involves  a  lot  of  time  and  effort  for  full  dumps,  dump  checkpoints  itself  at 
the  start  of  each  tape  volume.  If  writing  that  volume  fails  for  some  reason,  dump  will,  with 
operator  permission,  restart  itself  from  the  checkpoint  after  the  old  tape  has  been  rewound  and 
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removed,  and  a  new  tape  has  been  mounted. 

Dump  tells  the  operator  what  is  going  on  at  periodic  intervals,  including  usually  low  estimates  of 
the  number  of  blocks  to  write,  the  number  of  tapes  it  will  take,  the  time  to  completion,  and  the 
time  to  the  tape  change.  The  output  is  verbose,  so  that  others  know  that  the  terminal  control¬ 
ling  dump  is  busy,  and  will  be  for  some  time. 

Now  a  short  suggestion  on  how  to  perform  dumps.  Start  with  a  full  level  0  dump 
dump  Oun 

Next,  dumps  of  active  file  systems  are  taken  on  a  daily  basis,  using  a  modified  Tower  of  Hanoi 
algorithm,  with  this  sequence  of  dump  levels: 

3254769899... 

For  the  daily  dumps,  a  set  of  10  tapes  per  dumped  file  system  is  used  on  a  cyclical  basis.  Each 
week,  a  level  1  dump  is  taken,  and  the  daily  Hanoi  sequence  repeats  with  3.  For  weekly  dumps,  a 
set  of  5  tapes  per  dumped  file  system  is  used,  also  on  a  cyclical  basis.  Each  month,  a  level  0 
dump  is  taken  on  a  set  of  fresh  tapes  that  is  saved  forever. 

FILES 

/dev/rmt8  default  tape  unit  to  dump  to 
/etc/dumpdates  new  format  dump  date  record 
/etc/fstab  dump  table:  file  systems  and  frequency 

/etc/group  to  find  group  operator 

SEE  ALSO 

restore{8),  dump(5),  fstab(5) 

DIAGNOSTICS 

Many,  and  verbose. 

Dump  exit  codes  worthy  of  note  are: 

0  normal  exit  when  w  or  W  options  are  used. 

1  normal  exit. 

2  error  —  restart  writing  from  last  checkpoint. 

3  abort  —  no  checkpoint  attempted. 

BUGS 

Sizes  are  based  on  1600  BPI  blocked  tape;  the  raw  magtape  device  has  to  be  used  to  approach 
these  densities.  Fewer  than  32  read  errors  on  the  filesystem  are  ignored.  Each  reel  requires  a 
new  process,  so  parent  processes  for  reels  already  written  just  hang  around  until  the  entire  tape 
is  written. 

It  would  be  nice  if  dump  knew  about  the  dump  sequence,  kept  track  of  the  tapes  scribbled  on, 
told  the  operator  which  tape  to  mount  when,  and  provided  more  assistance  for  the  operator  run¬ 
ning  restore. 
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NAME 

dumpfs  —  dump  file  system  information 
SYNOPSIS 

/uBr/etc/dumpfB  device 
DESCRIPTION 

Dumpfs  prints  out  the  super  block  and  cylinder  group  information  for  the  file  system  or  special 
device  specified.  The  listing  is  very  long  and  detailed.  This  command  is  useful  mostly  for  finding 
out  certain  file  system  information  such  as  the  file  system  block  size  and  minimum  free  space  per¬ 
centage, 

SEE  ALSO 

fs(5),  tunefs(8),  newfs(8),  fsck(8) 
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NAME 

expire  —  remove  outdated  news  articles 
SYNOPSIS 

/uBr/Ilb/newa/explpe  [  ~n  newsgroups  1  I  — 1  ]  [  ~I )  |  — vj/eve/  j  ]  [  — e  days  )  [  —a  ] 

[-Pl(-hl 

DESCRIPTION 

Expire  is  normally  started  up  by  cron(8)  every  night  to  remove  all  expired  news.  If  no  news- 
groups  are  specified,  the  default  is  to  expire  all. 

Articles  whose  specified  expiration  date  has  already  passed  are  considered  expirable, 

OPTIONS 

— n  newsgroups 

List  of  newsgroups  to  expire.  Elements  in  the  list  of  newsgroups  must  be  separated  by 
commas  and/or  spaces. 

—a  archive  articles  in  /usr/spool/oldnews.  Articles  are  unlinked  in  the  absence  of  the  —a 
option. 

— v(/ere/] 

be  more  verbose.  A  verbosity  level  (default  1)  can  follow  the  — v  flag,  as  in  — v3  for  even 
more  output.  This  is  useful  if  articles  aren’t  being  expired  and  you  want  to  know  why. 

— e  days 

give  the  number  of  days  to  use  for  a  default  expiration  date.  If  not  given,  an  installation 
dependent  default  (often  2  weeks)  is  used.  Note  that  you  must  use  a  space  between  — e 
and  days. 

—I  ignore  any  expiration  date  explicitly  given  on  articles.  This  can  be  used  when  disk  space 
is  really  tight.  —I  always  ignores  expiration  dates,  while  —I  only  ignores  the  date  if 
ignoring  it  would  expire  the  article  sooner.  WARNING:  If  you  have  articles  archived  by 
giving  them  expiration  dates  far  into  the  future,  these  options  might  remove  these  files 
anyway. 

— r  rebuild  the  history  file  without  removing  any  files.  In  the  process,  expire  formats  the 

dbm[Z)  format  files  associated  with  the  history  file. 

— h  expire  articles  without  using  the  history  file.  Both  the  — r  and  — h  flags  use  the  active 

file  for  newsgroup  information  rather  than  the  history  file. 

SEE  ALSO 

checknews(l),  inews(l),  readnews(l),  recnews(8),  sendnews(8),  uurec(8) 


606 


Last  change:  1  February  1985 


Sun  Release  2.0 


FASTB00T(8) 


MAINTENANCE  COMMANDS 


FASTBOOT(8) 


NAME 

fastboot,  fasthalt  —  reboot/halt  the  system  without  checking  the  disks 
SYNOPSIS 

/etc/faatboot  [  boot-options  | 

/etc/fasthalt  [  halt- options  | 

DESCRIPTION 

Fastboot  and  fasthalt  arc  shell  scripts  which  reboot  and  halt  the  system  without  checking  the  file 
systems.  This  is  done  by  creating  a  file  /fastboot^  then  invoking  the  reboot  program.  The  system 
startup  script,  jetcfrCf  looks  for  this  file  and,  if  present,  skips  the  normal  invocation  of /?cJt(8). 

SEE  ALSO 

halt(8),  reboot(8),  rc(8) 
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NAME 

fsck  —  file  system  consistency  check  and  interactive  repair 
SYNOPSIS 

/etc/fsck  — p  [  filesystem  ...  ] 

/etc/fsck  [  — b  block#  j  [  —y  1  (  — n  ]  [  filesystem  ]  ... 

DESCRIPTION 

The  first  form  of  feck  preens  a  standard  set  of  filesystems  or  the  specified  file  systems.  It  is  nor¬ 
mally  used  in  the  script  /etc/rc  during  automatic  reboot.  In  this  case  fsck  reads  the  table 
/etc/fstab  to  determine  which  file  systems  to  check.  It  uses  the  information  there  to  inspect 
groups  of  disks  in  parallel  taking  maximum  advantage  of  i/o  overlap  to  check  the  file  systems  as 
quickly  as  possible.  Normally^  the  root  file  system  will  be  checked  on  pass  1,  other  ‘^root”  (“a” 
partition)  file  systems  on  pass  2,  other  small  file  systems  on  separate  passes  (e.g.  the  *‘d”  file  sys¬ 
tems  on  pass  3  and  the  *‘e”  file  systems  on  pass  4),  and  finally  the  large  user  file  systems  on  the 
last  pass,  e.g.  pass  5.  A  pass  number  of  0  in  fstab  causes  a  disk  to  not  be  checked;  similarly  par¬ 
titions  which  are  not  shown  as  to  be  mounted  ‘*rw”  or  “ro”  are  not  checked. 

The  system  takes  care  that  only  a  restricted  class  of  innocuous  inconsistencies  can  happen  unless 
hardware  or  software  failures  intervene.  These  are  limited  to  the  following: 

Unreferenced  inodes 

Link  counts  in  inodes  too  large 

Missing  blocks  in  the  free  list 

Blocks  in  the  free  list  also  in  files 

Counts  in  the  super-block  wrong 

These  are  the  only  inconsistencies  which  fsck  with  the  — p  option  will  correct;  if  it  encounters 
other  inconsistencies,  it  exits  with  an  abnormal  return  status  and  an  automatic  reboot  will  then 
fail.  For  each  corrected  inconsistency  one  or  more  lines  will  be  printed  identifying  the  file  system 
on  which  the  correction  will  take  place,  and  the  nature  of  the  correction.  After  successfully 
correcting  a  file  system,  fsck  will  print  the  number  of  files  on  that  file  system  and  the  number  of 
used  and  free  blocks. 

Without  the  — p  option,  fsck  audits  and  interactively  repairs  inconsistent  conditions  for  file  sys¬ 
tems.  If  the  file  system  is  inconsistent  the  operator  is  prompted  for  concurrence  before  each 
correction  is  attempted.  It  should  be  noted  that  a  number  of  the  corrective  actions  which  are 
not  fixable  under  the  — p  option  will  result  in  some  loss  of  data.  The  amount  and  severity  of 
data  lost  may  be  determined  from  the  diagnostic  output.  The  default  action  for  each  consistency 
correction  is  to  wait  for  the  operator  to  respond  yes  or  no.  If  the  operator  does  not  have  write 
permission  fsck  will  default  to  a  — n  action. 

Fsck  has  more  consistency  checks  than  its  predecessors  check,  dcheck,  fcheck,  and  icheck  com¬ 
bined. 

The  following  flags  are  interpreted  by  fsck, 

— b  Use  the  block  specified  immediately  after  the  flag  as  the  super  block  for  the  file  system. 

Block  32  is  always  an  alternate  super  block. 

— y  Assume  a  yes  response  to  all  questions  asked  by  fsck;  this  should  be  used  with  great  cau¬ 

tion  as  this  is  a  free  license  to  continue  after  essentially  unlimited  trouble  has  been  encoun¬ 
tered. 

— n  Assume  a  no  response  to  all  questions  asked  by  fsck;  do  not  open  the  file  system  for  writ¬ 

ing. 
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If  no  filesystems  are  given  to  fsck  then  a  default  list  of  file  systems  is  read  from  the  file 

/etc/fstab. 

Inconsistencies  checked  are  as  follows: 

1.  Blocks  claimed  by  more  than  one  inode  or  the  free  list. 

2.  Blocks  claimed  by  an  inode  or  the  free  list  outside  the  range  of  the  file  system. 

3.  Incorrect  link  counts. 

4.  Size  checks: 

Directory  size  not  of  proper  format. 

5.  Bad  inode  format. 

6.  Blocks  not  accounted  for  anywhere. 

7.  Directory  checks: 

File  pointing  to  unallocated  inode. 

Inode  number  out  of  range. 

8.  Super  Block  checks: 

More  blocks  for  inodes  than  there  are  in  the  file  system. 

9.  Bad  free  block  list  format. 

10.  Total  free  block  and/or  free  inode  count  incorrect. 

Orphaned  files  and  directories  (allocated  but  unreferenced)  are,  with  the  operator’s  concurrence, 
reconnected  by  placing  them  in  the  lost-ffound  directory.  The  name  assigned  is  the  inode 
number.  The  only  restriction  is  that  the  directory  lost+found  must  preexist  in  the  root  of  the 
filesystem  being  checked  and  must  have  empty  slots  in  which  entries  can  be  made.  This  is 
accomplished  by  making  lost+found,  copying  a  number  of  files  to  the  directory,  and  then 
removing  them  (before  fsck  is  executed). 

Checking  the  raw  device  is  almost  always  faster. 

FILES 

/etc/fstab  contains  default  list  of  file  systems  to  check. 

DIAGNOSTICS 

The  diagnostics  produced  by  fsck  are  intended  to  be  self-explanatory. 

SEE  ALSO 

fstab(6),  fs(5),  newfs(8),  mkfs(8),  crash(8S),  reboot(8) 

BUGS 

Inode  numbers  for  .  and  ..  in  each  directory  should  be  checked  for  validity. 

There  should  be  some  way  to  start  a  fsck  — p  at  pass  n. 
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NAME 

fsirand  —  install  random  inode  generation  numbers 

SYNOPSIS 

fsirand  |  — p  |  special 

DESCRIPTION 

Fsirand  installs  random  inode  generation  numbers  on  all  the  inodes  on  device  special,  and  also 
installs  a  filesystem  ID  in  the  superblock.  This  helps  increase  the  security  of  filesystems  exported 
by  NFS, 

Fsirand  must  be  used  only  on  an  unmounted  filesystem  that  has  been  checked  with  fsck{S).  The 
only  exception  is  that  it  can  be  used  on  the  root  filesystem  in  single-user  mode,  if  the  system  is 
immediately  re-booted  afterwords, 

OPTIONS 

— p  Print  out  the  generation  numbers  for  all  the  inodes,  but  do  not  change  the  generation 

numbers. 
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NAME 

ftpd  -  DARPA  Internet  File  Transfer  Protocol  server 
SYNOPSIS 

/uar/etc/ln.ffcpd  host.socket 
DESCRIPTION 

Ftpd  is  the  DARPA  Internet  File  Transfer  Prototocol  server  process.  The  server  is  invoked  by 
the  Internet  daemon  me<rf(8C)  each  time  a  connection  to  the  ftp  service  (see  sert;tces(5))  is  made, 
with  the  connection  available  as  descriptor  0  and  the  host  and  socket  the  connection  originated 
from  (in  hex  and  decimal  respectively)  as  argument. 

Inactive  connections  are  timed  out  after  60  seconds. 

The  ftp  server  currently  supports  the  following  ftp  requests;  case  is  not  distinguished. 


Request 

Description 

ACCT 

specify  account  (ignored) 

ALLO 

allocate  storage  (vacuously) 

APPE 

append  to  a  file 

CWD 

change  working  directory 

DELE 

delete  a  file 

HELP 

give  help  information 

LIST 

give  list  files  in  a  directory  (“Is  -Ig’*) 

MODE 

specify  data  transfer  mode 

NLST 

give  name  list  of  files  in  directory  (“Is”) 

NOOP 

do  nothing 

PASS 

specify  password 

PORT 

specify  data  connection  port 

QUIT 

terminate  session 

RETR 

retrieve  a  file 

RNFR 

specify  rename-from  file  name 

RNTO 

specify  rename-to  file  name 

STOR 

store  a  file 

STRU 

specify  data  transfer  structure 

TYPE 

specify  data  transfer  type 

USER 

specify  user  name 

XCUP 

change  to  parent  of  current  working  directory 

XeWD 

change  working  directory 

XMKD 

make  a  directory 

XPWD 

print  the  current  working  directory 

XRMD 

remove  a  directory 

The  remaining  ftp  requests  specified  in  Internet  RFC  765  are  recognized,  but  not  implemented. 

Ftpd  interprets  file  names  according  to  the  “globbing”  conventions  used  by  csA(l).  This  allows 

users  to  utilize  the  metacharacters 

Ftpd  authenticates  users  according  to  three  rules. 

1)  The  user  name  must  be  in  the  password  data  base,  fetcfpasswd,  and  not  have  a  null 
password.  In  this  case  a  password  must  be  provided  by  the  client  before  any  file  opera¬ 
tions  may  be  performed. 

2)  The  user  name  must  not  appear  in  the  file  /u$r/ ete/ftpueera. 

3)  If  the  user  name  is  “anonymous”  or  “ftp”,  an  anonymous  ftp  account  must  be  present  in 
the  password  file  (user  “ftp”).  In  this  case  the  user  is  allowed  to  log  in  by  specifying  any 
password  (by  convention  this  is  given  as  the  client  host’s  name). 
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In  the  last  case,  fipd  takes  special  measures  to  restrict  the  client’s  access  privileges.  The  server 
performs  a  chToot{2)  command  to  the  home  directory  of  the  “ftp”  user.  In  order  that  system 
security  is  not  breached,  it  is  recommended  that  the  “ftp”  subtree  be  constructed  with  care;  the 
following  rules  are  recommended. 

"ftp  Make  the  home  directory  owned  by  “ftp”  and  unwritable  by  anyone. 

~ftp/bin  Make  this  directory  owned  by  the  super- user  and  unwritable  by  anyone.  The  program 
l${l)  must  be  present  to  support  the  list  commands.  This  program  should  have  mode 
111. 

"ftp/etc  Make  this  directory  owned  by  the  super-user  and  unwritable  by  anyone.  The  files 
and  ^ro«p(5)  must  be  present  for  the  Is  command  to  work  properly.  These 
files  should  be  mode  444. 

"ftp/pub 

Make  this  directory  mode  777  and  owned  by  “ftp”.  Users  should  then  place  files  which 
are  to  be  accessible  via  the  anonymous  account  in  this  directory. 

SEE  ALSO 

ftp(lC),  ftpusers(5) 

BUGS 

There  is  no  support  for  aborting  commands. 

The  anonymous  account  is  inherently  dangerous  and  should  avoided  when  possible. 

The  server  must  run  as  the  super-user  to  create  sockets  with  privileged  port  numbers.  It  main¬ 
tains  an  effective  user  id  of  the  logged  in  user,  reverting  to  the  super-user  only  when  binding 
addresses  to  sockets.  The  possible  security  holes  have  been  extensively  scrutinized,  but  are  possi¬ 
bly  incomplete. 


512 


Last  change:  23  October  1984 


Sun  Release  2.0 


GETTABLE(8C) 


MAINTENANCE  COMMANDS 


GETTABLE(8C) 


NAME 

gettable  —  get  NIC  format  host  tables  from  a  host 

SYNOPSIS 

/etc/gettable  host 

DESCRIPTION 

Gettable  is  a  simple  program  used  to  obtain  the  NIC  standard  host  tables  from  a  “nicname” 
server.  The  indicated  host  is  queried  for  the  tables.  The  tables,  if  retrieved,  are  placed  in  the  file 
hosts  Jxt. 

Gettable  operates  by  opening  a  TCP  connection  to  the  port  indicated  in  the  service  specification 
for  ‘‘nicname”.  A  request  is  then  made  for  ‘‘ALL”  names  and  the  resultant  information  is  placed 
in  the  output  file. 

Gettable  is  best  used  in  conjunction  with  the  hiabl€{S)  program  which  converts  the  NIC  standard 
file  format  to  that  used  by  the  network  library  lookup  routines. 

SEE  ALSO 

intro(3N),  htable(8) 

BUGS 

Should  allow  requests  for  only  part  of  the  database. 


Sun  Release  2.0 


Last  change:  4  March  1983 


513 


GETTY(8) 


MAINTENANCE  COMMANDS 


GETTY(8) 


NAME 

getty  —  set  terminal  mode 

SYNOPSIS 

/etc/getty  |  char  | 

DESCRIPTION 

Geiiy  is  invoked  by  ini^(8)  immediately  after  a  terminal  is  opened,  following  the  making  of  a  con¬ 
nection,  While  reading  the  name  getty  attempts  to  adapt  the  system  to  the  speed  and  type  of 
terminal  being  used. 

Inti  calls  getty  with  an  argument  specified  by  the  ttys  file  entry  for  the  terminal  line.  Arguments 
other  than  'O’  can  be  used  to  make  geiiy  treat  the  line  specially.  Refer  to  and  gettytab[b) 

for  descriptions  of  how  getty  uses  the  data  in  gettytab  to  set  up  the  terminal.  Normally,  it  sets 
the  speed  of  the  interface  to  300  baud,  specifies  that  raw  mode  is  to  be  used  (break  on  every 
character),  that  echo  is  to  be  suppressed,  and  either  parity  allowed.  It  types  a  banner  identifying 
the  system  (from  gethostname(2))  and  the  'login:’  message.  Then  the  user’s  name  is  read,  a  char¬ 
acter  at  a  time.  If  a  null  character  is  received,  it  is  assumed  to  be  the  result  of  the  user  pushing 
the  'break’  ('interrupt*)  key.  The  speed  is  then  changed  to  1200  baud  and  the  ‘login:’  is  typed 
again;  a  second  'break’  changes  the  speed  to  150  baud  and  the  'login:’  is  typed  again.  Successive 
‘break’  characters  cycle  through  the  speeds  300,  1200,  and  150  baud. 

The  user’s  name  is  terminated  by  a  new-line  or  carriage-return  character.  The  latter  results  in 
the  system  being  set  to  treat  carriage  returns  appropriately  (see  ^^y(4)). 

The  user’s  name  is  scanned  to  see  if  it  contains  any  lower-case  alphabetic  characters;  if  not,  and 
if  the  name  is  nonempty,  the  system  is  told  to  map  any  future  upper-case  characters  into  the 
corresponding  lower-case  characters. 

Finally,  login  is  called  with  the  user’s  name  as  argument. 

SEE  ALSO 

init(8),  login(l),  ioctI(2),  tty(4),  ttys(5),  gettytab(5) 
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NAME 

gxtest  —  stand  alone  test  for  the  Sun  video  graphics  board 

SYNOPSIS 

b  /stand/gxiest 

DESCRIPTON 

Gxttsl  runs  stand  alone,  not  under  control  of  the  UNIX  operating  system.  With  the  PROM 
resident  monitor  in  control  of  the  system,  type  the  command: 

>  b  /stand/gxtest 

and  the  monitor  boots  the  video  test  program  into  memory.  Gxteat  is  completely  self- 
explanatory  and  runs  under  its  own  steam.  It  reports  any  errors  it  finds  on  the  screen. 


Sun  Release  2.0 


Last  change:  23  March  1983 


515 


HALT (8) 


MAINTENANCE  COMMANDS 


HALT (8) 


NAME 

halt  —  stop  the  processor 
SYNOPSIS 

/ete/halt  [  -n  |  |  -q  I  [  -y  ] 

DESCRIPTION 

Halt  writes  out  sandbagged  information  to  the  disks  and  then  stops  the  processor. 
OPTIONS 

— n  Prevents  the  sync  before  stopping. 

—q  Do  a  quick  halt,  no  graceful  shutdown  is  attempted. 

— y  Needed  if  you  are  trying  to  halt  the  system  from  a  dialup. 

SEE  ALSO 

reboot(8),  shutdown(8) 
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NAME 

h table  —  convert  NIC  standard  format  host  tables 

SYNOPSIS 

/usr/etc/htable  file 

DESCRIPTION 

Htable  is  used  to  convert  host  files  in  the  format  specified  in  Internet  RFC  810  to  the  format 
used  by  the  network  library  routines.  Three  files  are  created  as  a  result  of  running  htable:  hoste^ 
networks,  and  gateways.  The  hosts  file  is  used  by  the  gethostent{SN)  routines  in  mapping  host 
names  to  addresses.  The  networks  file  is  used  by  the  getnetent{SN)  routines  in  mapping  network 
names  to  numbers.  The  gateways  file  is  used  by  the  routing  daemon  in  identifying  “passive” 
Internet  gateways;  see  ro«^erf(8C)  for  an  explanation. 

If  any  of  the  files  localhosts,  localnetworks,  or  localgateways  are  present  in  the  current  directory, 
the  file’s  contents  is  prepended  to  the  output  file  without  interpretation.  This  allows  sites  to 
maintain  local  aliases  and  entries  which  are  not  normally  present  in  the  master  database. 

Htable  is  best  used  in  conjunction  with  the  gettable{SC)  program  which  retrieves  the  NIC  data¬ 
base  from  a  host. 

SEE  ALSO 

intro(3N),  gettable(8C) 

BUGS 

Does  not  properly  calculate  the  gateways  file. 
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NAME 

icheck  -  file  system  storage  consistency  check 
SYNOPSIS 

/uBr/etc/lcheck  |  — e  |  [  — b  numbers  ]  |  filesystem  ) 

DESCRIPTION 

N.B.:  Icheck  is  obsoleted  for  normal  consistency  checking  by  /ffcl:(8). 

Icheck  examines  a  file  system,  builds  a  bit  map  of  used  blocks,  and  compares  this  bit  map  against 
the  free  list  maintained  on  the  file  system.  If  the  file  system  is  not  specified,  a  set  of  default  file 
systems  is  checked.  The  normal  output  of  icheck  includes  a  report  of 

The  total  number  of  files  and  the  numbers  of  regular,  directory,  block  special  and  char¬ 
acter  special  files. 

The  total  number  of  blocks  in  use  and  the  numbers  of  single-,  double-,  and  triple-indirect 
blocks  and  directory  blocks. 

The  number  of  free  blocks. 

The  number  of  blocks  missing;  i.e.  not  in  any  file  nor  in  the  free  list. 

The  — B  option  causes  icheck  to  ignore  the  actual  free  list  and  reconstruct  a  new  one  by  rewriting 
the  super-block  of  the  file  system.  The  file  system  should  be  dismounted  while  this  is  done;  if 
this  is  not  possible  (for  example  if  the  root  file  system  has  to  be  salvaged)  care  should  be  taken 
that  the  system  is  quiescent  and  that  it  is  rebooted  immediately  afterwards  so  that  the  old,  bad 
in-core  copy  of  the  super-block  will  not  continue  to  be  used.  Notice  also  that  the  words  in  the 
super-block  which  indicate  the  size  of  the  free  list  and  of  the  i-list  are  believed.  If  the  super¬ 
block  has  been  curdled  these  words  will  have  to  be  patched.  The  — b  option  causes  the  normal 
output  reports  to  be  suppressed. 

Following  the  — b  option  is  a  list  of  block  numbers;  whenever  any  of  the  named  blocks  turns  up 
in  a  file,  a  diagnostic  is  produced. 

Icheck  is  faster  if  the  raw  version  of  the  special  file  is  used,  since  it  reads  the  i-list  many  blocks  at 
a  time. 

FILES 

Default  file  systems  vary  with  installation. 

SEE  ALSO 

fsck(8),  dcheck(8),  ncheck(8),  fs(5),  clri(8) 

DIAGNOSTICS 

For  duplicate  blocks  and  bad  blocks  (which  lie  outside  the  file  system)  icheck  announces  the 
difficulty,  the  i-number,  and  the  kind  of  block  involved.  If  a  read  error  is  encountered,  the  block 
number  of  the  bad  block  is  printed  and  icheck  considers  it  to  contain  0.  ‘Bad  freeblock’  means 
that  a  block  number  outside  the  available  space  was  encountered  in  the  free  list,  ‘n  dups  in  free’ 
means  that  n  blocks  were  found  in  the  free  list  which  duplicate  blocks  either  in  some  file  or  in  the 
earlier  part  of  the  free  list. 

BUGS 

Since  icheck  is  inherently  two-pass  in  nature,  extraneous  diagnostics  may  be  produced  if  applied 
to  active  file  systems. 

It  believes  even  preposterous  super-blocks  and  consequently  can  get  core  images. 

The  system  should  be  fixed  so  that  the  reboot  after  fixing  the  root  file  system  is  not  necessary. 
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NAME 

ifconfig  —  configure  network  interface  parameters 
SYOPNSIS 

/etc/ifconflg  interface  [  Ethernei^address  ]  [  hostname  ]  [  parameters  \ 

DESCRIPTION 

Ifconfig  is  used  to  assign  an  address  to  a  network  interface  and/or  to  configure  network  interface 
parameters.  Ifconfig  must  be  used  at  boot  time  to  define  the  network  address  of  each  interface 
present  on  a  machine;  it  may  also  be  used  at  a  later  time  to  redefine  an  interface’s  address.  Used 
without  options,  ifconfig  displays  the  current  configuration  for  a  network  interface.  Only  the 
super-user  may  modify  the  configuration  of  a  network  interface. 

The  interface  parameter  is  a  string  of  the  form  “name  unit”,  for  example  “ieO”. 

OPTIONS 

Ethernet^address  is  the  hardware  Ethernet  address  of  a  given  machine.-  The  address  is  a  6-byte 
hexadecimal  value;  each  byte  of  the  address  is  separated  by  a  colon.  A  typical  Ethernet  adddress 
is  ‘8:0:20: 1:1  :A3’.  This  address  is  contained  in  the  ID  PROM  on  the  Sun-2  CPU  Board,  and  is 
reported  at  boot  time  as  one  of  the  PROM  monitor’s  sign-on  messages.  The  Ethernet^address 
option  is  normally  not  used  —  the  hardware  supplies  the  default;  the  option  is  used  only  when 
trying  to  talk  to  a  device  which  does  not  support  ARP  (like  a  VAX  on  a  4.1c  network). 

hostname  may  be  either  the  hostname  of  a  given  machine  (present  in  the  hostname  database, 
or  the  complete  Internet  address  consisting  of  your  system’s  network  number  and  the 
machine’s  unique  host  number.  A  typical  Internet  address  might  be  “192.9.200.44”,  where 
“192.9.200”  is  the  network  number  and  “44”  is  the  machine’s  hostnumber.  To  find  a  machine’s 
Internet  address,  consult  the  local  /etc/ hosts  file. 

The  following  parameters  may  be  set  with  ifconfig: 

up  Mark  an  interface  “up”. 

down  Mark  an  interface  “down”.  When  an  interface  is  marked  “down”,  the  system 

will  not  attempt  to  transmit  messages  through  that  interface. 

trailers  Enable  the  use  of  a  “trailer”  link  level  encapsulation  when  sending  (default).  If 
a  network  interface  supports  trailers,  the  system  will,  when  possible,  encapsulate 
outgoing  messages  in  a  manner  which  minimizes  the  number  of  memory  to 
memory  copy  operations  performed  by  the  receiver. 

—trailers  Disable  the  use  of  a  “trailer”  link  level  encapsulation. 

arp  Enable  the  use  of  the  Address  Resolution  Protocol  in  mapping  between  network 

level  addresses  and  link  level  addresses  (default).  This  is  currently  implemented 
for  mapping  between  DARPA  Internet  addreses  and  lOMb/s  Ethernet  addresses. 

—arp  Disable  the  use  of  the  Address  Resolution  Protocol. 

DIAGNOSTICS 

Messages  indicating  the  specified  interface  does  not  exit,  the  requested  address  is  unknown,  the 
user  is  not  privileged  and  tried  to  alter  an  interface’s  configuration. 

SEE  ALSO 

rc(8),  intro(4N),  netstat(l) 
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NAME 

imemtest  —  stand  alone  memory  test 
SYNOPSIS 


b  /Bt&nd/Imemteat 
DESCRIPTON 

Imemtest  runs  stand  alone,  not  under  control  of  the  UNIX  operating  system, 
resident  monitor  in  control  of  the  system,  type  the  command: 


With  the  PROM 


>  b  /stand/imemtest 

and  the  monitor  boots  the  memory  test  program  into  memory.  Imemtest  is  completely  self- 
explanatory.  It  prompts  for  all  start  and  end  addresses,  and  after  that  it  runs  under  its  own 
steam.  It  reports  any  errors  it  finds  on  the  screen. 
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NAME 

inetd  —  internet  services  daemon 

SYNOPSIS 

/etc/inetd  [  — d  | 

DESCRIPTION 

Inetd  is  the  internet  super-server  which  invokes  all  internet  server  processes  as  needed. 
Connection-oriented  services  are  invoked  each  time  a  connection  is  made,  by  creating  a  process. 
This  process  is  passed  the  connection  as  file  descriptor  0  and  an  argument  of  the  form 
“sourcehost.sourceport”  where  sourcehost  is  hex  and  sourceport  is  decimal. 

Datagram  oriented  services  are  invoked  when  a  datagram  arrives;  a  process  is  created  and  passed 
the  connection  as  file  descriptor  0.  Inetd  will  look  at  the  socket  where  datagrams  arrive  again 
only  after  this  process  completes.  The  paradigms  for  such  proceses  are  either  to  read  off  the 
incoming  datagram  and  then  fork  and  exit,  or  to  process  the  arriving  datagram  and  then  time 
out. 

Inetd  consults  9erver$[h)  when  it  is  invoked,  and  supports  whatever  services  are  in  that  file. 

An  rep  server  can  be  started  from  inetd.  The  only  differences  from  the  usual  code  are  that 
svcudp_create  should  be  called  as: 

transp  =  scvudp_create(0) 

since  inet  passes  a  socket  file  as  descriptor  0,  and  svc_register  should  be  called  as: 

svc_register(PROGNUM,  VERSNUM,  service,  transp,  0) 

with  the  final  flag  as  0,  since  the  program  will  already  have  been  registered  by  inetd.  If  you  want 
to  exit  from  the  server  process  and  return  control  to  inet,  you  must  explicitly  exit  since  sev^run 
never  returns. 

The  format  of  entries  in  f  etej serverz  for  rpc  services  is: 

rep  udp  zetver-^ro^ram  program-number  version-number 

where  server-program  is  the  C  code  implementing  the  server,  and  program-number,  version- 
number  are  the  program,  and  version  numbers,  respectively  of  the  service.  The  keyword  udp 
can  be  replaced  by  tep  for  ^cp-based  services. 

If  the  same  program  handles  multiple  versions,  the  version  number  can  be  specified  as  a  range: 

rep  udp  /usr/etc/rstatd  100001  1^2 

OPTIONS 

— d  Specifies  that  debugging  traces  are  to  be  turned  on  for  connection-oriented  (TCP)  ser¬ 

vices. 

FILES 

/etc/servers  list  of  internet  server  processes 
SEE  ALSO 

servers(5),  comsat(8C),  ftpd(8C),  rexecd(8C),  rlogind(8C),  sysIog(8),  rshd(8C),  talkd(8C), 
telnetd(8C),  tftpd(8C) 

BUGS 

There  is  no  provision  for  selectively  invoking  TCP  debugging  packet  tracing  per-service. 

Should  reread  the  fetef servers  file  on  receipt  of  a  SIGHUP  signal.  The  [etc! servers  file  can 
have  no  more  than  26  lines. 
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NAME 

init  —  process  control  initialization 

SYNOPSIS 

/etc/lnit 

DESCRIPTION 

Inii  is  invoked  inside  UNIX  as  the  last  step  in  the  boot  procedure.  It  normally  then  runs  the 
automatic  reboot  sequence  as  described  in  r€boot{6),  and  if  this  succeeds,  begins  multi-user 
operation.  If  the  reboot  fails,  it  commences  smgle  user  operation  by  giving  the  super-user  a  shell 
on  the  console.  It  is  possible  to  pass  parameters  from  the  boot  program  to  init  so  that  single  user 
operation  is  commenced  immediately.  When  such  single  user  operation  is  terminated  by  killing 
the  single-user  shell  (i.e.  by  hitting  "D),  init  runs  /ttcfrc  without  the  reboot  parameter.  This 
command  file  performs  housekeeping  operations  such  as  removing  temporary  files,  mounting  file 
systems,  and  starting  daemons. 

In  multi-user  operation,  init^e  role  is  to  create  a  process  for  each  terminal  port  on  which  a  user 
may  log  in.  To  begin  such  operations,  it  reads  the  file  (etc/tty8  and  forks  several  times  to  create 
a  process  for  each  terminal  specified  in  the  file.  Each  of  these  processes  opens  the  appropriate 
terminal  for  reading  and  writing.  These  channels  thus  receive  file  descriptors  0,  1  and  2,  the 
standard  input  and  output  and  the  diagnostic  output.  Opening  the  terminal  will  usually  involve 
a  delay,  since  the  open  is  not  completed  until  someone  is  dialed  up  and  carrier  established  on  the 
channel.  If  a  terminal  exists  but  an  error  occurs  when  trying  to  open  the  terminal  init  complains 
by  writing  a  message  to  the  system  console;  the  message  is  repeated  every  10  minutes  for  each 
such  terminal  until  the  terminal  is  shut  off  in  /etc/ttys  and  init  notified  (by  a  hangup,  as 
described  below),  or  the  terminal  becomes  accessible  (init  checks  again  every  minute).  After  an 
open  succeeds,  /etc/getty  is  called  with  argument  as  specified  by  the  second  character  of  the  ttya 
file  line.  Getty  reads  the  user’s  name  and  invokes  login  to  log  in  the  user  and  execute  the  Shell. 

Ultimately  the  Shell  will  terminate  because  of  an  end-of-file  either  typed  explicitly  or  generated 
as  a  result  of  hanging  up.  The  main  path  of  init,  which  has  been  waiting  for  such  an  event, 
wakes  up  and  removes  the  appropriate  entry  from  the  file  utmp,  which  records  current  users,  and 
makes  an  entry  in  /usr/adm/wtmp,  which  maintains  a  history  of  logins  and  logouts.  The  wtmp 
entry  is  made  only  if  a  user  logged  in  successfully  on  the  line.  Then  the  appropriate  terminal  is 
reopened  and  getty  is  reinvoked. 

Init  catches  the  hangup  signal  (signal  SIGHUP)  and  interprets  it  to  mean  that  the  file  j etc/ ttya 
should  be  read  again.  The  Shell  process  on  each  line  which  used  to  be  active  in  ttya  but  is  no 
longer  there  is  terminated;  a  new  process  is  created  for  each  added  line;  lines  unchanged  in  the 
file  are  undisturbed.  Thus  it  is  possible  to  drop  or  add  phone  lines  without  rebooting  the  system 
by  changing  the  ttya  file  and  sending  a  hangup  signal  to  the  init  process:  use  ‘kill  —HUP  1.* 

Init  will  terminate  multi-user  operations  and  resume  single-user  mode  if  sent  a  terminate  (TERM) 
signal,  i.e.  “kill  —TERM  1”.  If  there  are  processes  outstanding  which  are  deadlocked  (due  to 
hardware  or  software  failure),  init  will  not  wait  for  them  all  to  die  (which  might  take  forever), 
but  will  time  out  after  30  seconds  and  print  a  warning  message. 

Init  will  cease  creating  new  getty's  and  allow  the  system  to  slowly  die  away,  if  it  is  sent  a  termi¬ 
nal  stop  (TSTP)  signal,  i.e.  “kill  — TSTP  1’’.  A  later  hangup  will  resume  full  multi-user  opera¬ 
tions,  or  a  terminate  will  initiate  a  single  user  shell.  This  hook  is  used  by  r€boot{S)  and  ftaW(8). 

Init'a  role  is  so  critical  that  if  it  dies,  the  system  will  reboot  itself  automatically.  If,  at  bootstrap 
time,  the  inii  process  cannot  be  located,  the  system  will  loop  in  user  mode  at  location  0x13. 

DIAGNOSTICS 

Init:  ttyi  cannot  open.  A  terminal  which  is  turned  on  in  the  re  file  cannot  be  opened,  likely 
because  the  requisite  lines  are  either  not  configured  into  the  system  or  the  associated  device  was 
not  attached  during  boot-time  system  configuration. 
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WARNINGj  Something  is  hung  (wont  die)|  ps  axl  advised.  A  process  is  hung  and  could 
not  be  killed  when  the  system  was  shutting  down.  This  is  usually  caused  by  a  process  which  is 
stuck  in  a  device  driver  due  to  a  persistent  device  error  condition. 

FILES 

/dev/console,  /dev/tty*,  /etc/utmp,  /usr/adm/wtmp,  /etc/ttys,  /etc/rc 
SEE  ALSO 

login(l),  kin(l),  sh(l),  ttys(5),  getty(8),  rc(8),  reboot(8),  halt(8),  shutdown(8) 
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NAME 

iostat  —  report  I/O  statistics 
SYNOPSIS 

Iostat  I  interval  [  count  ]  ] 

DESCRIPTION 

Iostat  iteratively  reports  the  number  of  characters  read  and  written  to  terminals,  and,  for  each 
disk,  the  number  of  seeks  and  transfers  per  second,  and  the  milliseconds  per  average  seek.  It  also 
gives  the  percentage  of  time  the  system  has  spent  in  user  mode,  in  user  mode  running  low  prior¬ 
ity  (niced)  processes,  in  system  mode,  and  idling. 

To  compute  this  information,  for  each  disk,  seeks  and  data  transfer  completions  and  number  of 
words  transferred  are  counted;  for  terminals  collectively,  the  number  of  input  and  output  charac¬ 
ters  are  counted.  Also,  each  fiftieth  of  a  second,  the  state  of  each  disk  is  examined  and  a  tally  Is 
made  if  the  disk  is  active.  From  these  numbers  and  given  the  transfer  rates  of  the  devices  it  is 
possible  to  determine  average  seek  times  for  each  device. 

The  optional  interval  argument  causes  iostat  to  report  once  each  interval  seconds.  The  first 
report  is  for  all  time  since  a  reboot  and  each  subsequent  report  is  for  the  last  interval  only. 

The  optional  count  argument  restricts  the  number  of  reports. 

FILES 

/dev/kmem 

/vmunix 

SEE  ALSO 

vmstat(8) 
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NAME 

kgmon  —  generate  a  dump  of  the  operating  system’s  profile  buffers 
SYNOPSIS 

/uar/etc/kgmon  [  — b  j  [  — h  ]  [  — r  |  |  — p  |  (  system  j  |  memory  ] 

DESCRIPTION 

Kgmon  is  a  tool  used  when  profiling  the  operating  system.  When  no  arguments  are  supplied, 
kgmon  indicates  the  state  of  operating  system  profiling  as  running,  off,  or  not  configured  (see 
con^^(8)).  If  the  — p  flag  is  specified,  kgmon  extracts  profile  data  from  the  operating  system  and 
produces  a  gmon.out  file  suitable  for  later  analysis  by  gprof{l), 

OPTIONS 

—b  Resume  the  collection  of  profile  data. 

—h  Stop  the  collection  of  profile  data. 

— p  Dump  the  contents  of  the  profile  buffers  into  a  gmon,out  file. 

— r  Reset  all  the  profile  buffers.  If  the  — p  flag  is  also  specified,  the  gmon.ont  file  is  generated 

before  the  buffers  are  reset. 

If  neither  — b  nor  — h  is  specified,  the  state  of  profiling  collection  remains  unchanged.  For  exam¬ 
ple,  if  the  —p  flag  is  specified  and  profile  data  is  being  collected,  profiling  is  momentarily 
suspended,  the  operating  system  profile  buffers  are  dumped,  and  profiling  is  immediately 
resumed. 

FILES 

/vmunix  —  the  default  system 
/dev/kmem  --  the  default  memory 

SEE  ALSO 

gprof  (1),  config(8) 

DIAGNOSTICS 

Users  with  only  read  permission  on  /dev/kmem  cannot  change  the  state  of  profiling  collection. 
They  can  get  a  gmon,out  file  with  the  warning  that  the  data  may  be  inconsistent  if  profiling  is  in 
progress. 
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NAME 

Ipc  —  line  printer  control  program 
SYNOPSIS 

/usr/etc/lpc  (  command  [  command-parameter  ]  | 

DESCRIPTION 

Lpc  is  the  Line  Printer  Control  program  and  is  used  by  the  system  administrator  to  control  the 
operation  of  the  line  printer  system.  For  each  line  printer  configured  in  /etc/printcap  (the  line 
printer  description  database),  lpc  may  be  used  to: 

#  disable  or  enable  a  printer, 

•  disable  or  enable  a  printer’s  spooling  queue, 

•  rearrange  the  order  of  jobs  in  a  spooling  queue, 

#  find  the  status  of  printers,  and  their  associated  spooling  queues  and  printer  daemons. 

Without  any  arguments,  lpc  works  interactively  and  prompts  for  commands  from  the  standard 
input.  If  arguments  are  supplied,  lpc  interprets  the  first  argument  as  a  command  and  the 
remaining  arguments  as  parameters  to  the  command.  The  standard  input  may  be  redirected  so 
that  lpc  reads  commands  from  a  file.  Commands  may  be  abreviated;  the  following  is  the  list  of 
recognized  commands.  Note  that  the  printer  parameter  in  the  commands  is  specified  just  by  the 
name  of  the  printer  (prlntronlx  for  example),  not  by  -Pprlntronlx  as  you  would  specify  it  to 
the  Ipr  or  Ipq  commands. 

?  I  command  ...  ] 
help  I  command  ...  | 

Display  a  short  description  of  each  command  specified  in  the  argument  list,  or,  if  no 
arguments  are  given,  a  list  of  the  recognized  commands. 

abort  {  all  j  printer  ...  } 

Terminate  an  active  spooling  daemon  on  the  local  host  immediately  and  then  disable 
printing  (preventing  new  daemons  from  being  started  by  Ipr)  for  the  specified  printers. 
The  abort  command  can  only  be  used  by  the  super-user. 

clean  {  all  j  printer  ...  } 

Remove  all  files  beginning  with  ‘cf,  *tr,  or  ‘df’  from  the  specified  printer  queue(s)  on  the 
local  machine.  The  clean  command  can  only  be  used  by  the  super-user. 

enable  {  all  j  printer  ...  } 

Enable  spooling  on  the  local  queue  for  the  listed  printers,  so  that  Ipr  can  put  new  jobs  in 
the  spool  queue.  The  enable  command  can  only  be  used  by  the  super-user. 

exit 

quit 

Exit  from  lpc, 
disable  {  all  |  printer  ...  } 

Turn  the  specified  printer  queues  off.  This  prevents  new  printer  jobs  from  being  entered 
into  the  queue  by  Ipr,  The  disable  command  can  only  be  used  by  the  super-user. 

restart  {  all  |  printer  ...  } 

Attempt  to  start  a  new  printer  daemon.  This  is  useful  when  some  abnormal  condition 
causes  the  daemon  to  die  unexpectedly  leaving  jobs  in  the  queue.  Lpq  reports  that  there 
is  no  daemon  present  when  this  condition  occurs. 

start  {  all  j  printer  ...  } 

Enable  printing  and  start  a  spooling  daemon  for  the  listed  printers.  The  start  command 
can  only  be  used  by  the  super-user. 

status  I  all  ]  [  printer  ...  j 

Display  the  status  of  daemons  and  queues  on  the  local  machine. 
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stop  {  all  I  printer  ...  } 

Stop  a  spooling  daemon  after  the  current  job  completes  and  disable  printing.  The  stop 
command  can  only  be  used  by  the  super-user. 

topq  printer  [jobnum  ...j  [user  ...] 

Move  the  print  job(s)  specified  by  johnum  or  those  job(s)  belonging  to  user  to  the  top 
(head)  of  the  printer  queue.  The  topq  command  can  only  be  used  by  the  super-user. 

FILES 

/etc/printcap  printer  description  file 

/usr/spool/*  spool  directories 

/usr/spool/*/lock  lock  file  for  queue  control 

SEE  ALSO 

lpd(8),  Ipr(l),  Ipq(l),  Iprm(l),  printcap(5) 

DIAGNOSTICS 

TAmbiguous  command  abreviation  matches  more  than  one  command 
?Invalid  command  no  match  was  found 

?PriviIeged  command  command  can  be  executed  by  super-user  only 
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NAME 

Ipd  —  line  printer  daemon 
SYNOPSIS 

/usr/lib/lpd  [  -1 1  I  -L  logfile  I  [  port  #  ] 

DESCRIPTION 

Lpd  is  the  line  printer  daemon  (spool  area  handler)  and  is  normally  invoked  at  boot  time  from 
the  rc(8)  file.  It  makes  a  single  pass  through  the  prm^cap(5)  file  to  find  out  about  the  existing 
printers  and  prints  any  files  left  after  a  crash.  It  then  uses  the  system  calls  li$ten{2)  and  accepi{2) 
to  receive  requests  to  print  files  in  the  queue,  transfer  files  to  the  spooling  area,  display  the 
queue,  or  remove  jobs  from  the  queue.  In  each  case,  it  forks  a  child  to  handle  the  request  so  the 
parent  can  continue  to  listen  for  more  requests.  The  Internet  port  number  used  to  rendezvous 
with  other  processes  is  normally  obtained  with  ire^^eruen/(3N)  but  can  be  changed  with  the 
port#  argument.  The  — L  option  changes  the  file  used  for  writing  error  conditions  from  the  sys¬ 
tem  console  to  logfile.  The  —1  flag  causes  lpd  to  log  valid  requests  received  from  the  network. 
This  can  be  useful  for  debugging  purposes. 

Access  control  is  provided  by  two  means.  First,  all  requests  must  come  from  one  of  the  machines 
listed  in  the  file  /etc/ hosts. equiv.  Second,  if  the  “rs’*  capability  is  specified  in  the  printcap  entry 
for  the  printer  being  accessed,  Ipr  requests  will  only  be  honored  for  those  users  with  accounts  on 
the  machine  with  the  printer. 

The  file  lock  in  each  spool  directory  is  used  to  prevent  multiple  daemons  from  becoming  active 
simultaneously,  and  to  store  information  about  the  daemon  process  for  /pr(l),  and 

fprm(l).  After  the  daemon  has  successfully  set  the  lock,  it  scans  the  directory  for  files  beginning 
with  c/.  Lines  in  each  cf  file  specify  files  to  be  printed  or  non-printing  actions  to  be  performed. 
Each  such  line  begins  with  a  key  character  to  specify  what  to  do  with  the  remainder  of  the  line. 

J  Job  Name,  String  to  be  used  for  the  job  name  on  the  burst  page. 

C  Classification.  String  to  be  used  for  the  classification  line  on  the  burst  page. 

L  Literal.  The  line  contains  identification  info  from  the  password  file  and  causes  the 

banner  page  to  be  printed, 

T  Title.  String  to  be  used  as  the  title  for  pr(l). 

H  Host  Name.  Name  of  the  machine  where  Ipr  was  invoked. 

P  Person.  Login  name  of  the  person  who  invoked  Ipr.  This  is  used  to  verify  ownership  by 
Iprm. 

M  Send  mail  to  the  specified  user  when  the  current  print  job  completes, 

f  Formatted  File.  Name  of  a  file  to  print  which  is  already  formatted. 

!  Like  “f”  but  passes  control  characters  and  does  not  make  page  breaks, 
p  Name  of  a  file  to  print  using  pr(l)  as  a  filter. 

t  Troff  File,  The  file  contains  troff{l)  output  (C/A/T  phototypesetter  commands), 
d  DVI  File.  The  file  contains  output  (DVI  format  from  Stanford), 
g  Graph  File.  The  file  contains  data  produced  by  plot{dX). 

c  Cifplot  File.  The  file  contains  data  produced  by  cifplot. 

V  The  file  contains  a  raster  image. 

r  The  file  contains  text  data  with  FORTRAN  carriage  control  characters. 

1  Troff  Font  R.  Name  of  the  font  file  to  use  instead  of  the  default. 

2  Troff  Font  I.  Name  of  the  font  file  to  use  instead  of  the  default. 
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3  Troff  Font  B.  Name  of  the  font  file  to  use  instead  of  the  default. 

4  Troff  Font  S.  Name  of  the  font  file  to  use  instead  of  the  default. 

W  Width.  Changes  the  page  width  (in  characters)  used  by  pr(l)  and  the  text  filters. 

I  Indent.  The  number  of  characters  to  indent  the  output  by  (in  ascii), 

U  Unlink.  Name  of  file  to  remove  upon  completion  of  printing. 

N  File  name.  The  name  of  the  file  which  is  being  printed,  or  a  blank  for  the  standard  input 
(when  Ipr  is  invoked  in  a  pipeline). 

If  a  file  can  not  be  opened,  a  message  will  be  placed  in  the  log  file  (normally  the  console).  Lpd 
will  try  up  to  20  times  to  reopen  a  file  it  expects  to  be  there,  after  which  it  will  skip  the  file  to  be 
printed. 

Lpd  uses  /lock(2)  to  provide  exclusive  access  to  the  lock  file  and  to  prevent  multiple  deamons 
from  becoming  active  simultaneously.  If  the  daemon  should  be  killed  or  die  unexpectedly,  the 
lock  file  need  not  be  removed.  The  lock  file  is  kept  in  a  readable  ASCII  form  and  contains  two 
lines.  The  first  is  the  process  id  of  the  daemon  and  the  second  is  the  control  file  name  of  the 
current  job  being  printed.  The  second  line  is  updated  to  reflect  the  current  status  of  lpd  for  the 
programs  Ipg(l)  and  Iprm(l), 


FILES 

/etc/printcap 

/usr/spool/* 

/dev/lp* 

/etc/hosts.equiv 


printer  description  file 
spool  directories 
line  printer  devices 

lists  machine  names  allowed  printer  access 


SEE  ALSO 

lpc(8),  pac(8),  Ipr(l),  Ipq(l),  Iprm(l),  printcap(5) 
4,2BSD  Line  Printer  Spooler  Manual 
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NAME 

makedbm  —  make  a  yellow  pages  dbm  file 
SYNOPSIS 

makedbm  [  —1  ypJnpuOle  ]  [  — o  yp_output_name  j  |  yp_domain_name  |  [  — m 
yp_master_name  |  infile  outfile 
makedbm  (  — u  dbmfilename  j 

DESCRIPTION 

Makedbm  takes  infile  and  converts  it  to  a  pair  of  files  in  rf^m(3X)  format,  namely  ouf/i/c.pag  and 
outfile  Air,  Each  line  of  the  input  file  is  converted  to  a  single  dbm  record.  All  characters  up  to 
the  first  tab  or  space  form  the  key,  and  the  rest  of  the  line  is  the  data.  If  a  line  ends  with  \,  then 
the  data  for  that  record  is  continued  on  to  the  next  line.  It  is  left  for  the  clients  of  the  yellow 
pages  to  interpret  #;  makedbm  does  not  itself  treat  it  as  a  comment  character.  Infile  can  be  — , 
in  which  case  standard  input  is  read. 

Makedbm  is  meant  to  be  used  in  generating  dbm  files  for  the  yellow  pages,  and  it  generates  a  spe¬ 
cial  entry  with  the  key  YP_LAST3IODIFIED,  which  is  the  date  of  infile  (or  the  current  time,  if 
infile  is  — ). 

OPTIONS 

Create  a  special  entry  with  the  key  YPJNPUTJ’ILE. 

— o  Create  a  special  entry  with  the  key  YP_OUTPUT_NAME. 

— d  Create  a  special  entry  with  the  key  YPJ)OMAIN_NAME. 

— m  Create  a  special  entry  with  the  key  YP_MASTERJMAME. 

— u  Undo  a  dbm  file.  That  is,  print  out  a  dbm  file  one  entry  per  line,  with  a  single  space 

separating  keys  from  values, 

EXAMPLE 

It  is  easy  to  write  shell  scripts  to  convert  standard  files  such  as  f  etc/passwd  to  the  key  value 
form  used  by  makedbm.  For  example, 

#!/bin/awk 

BEGIN  {  FS  =  OFS  =  } 

{  print  $1,  $0  } 

takes  the  f  etc/passwd  file  and  converts  it  to  a  form  that  can  be  read  by  makedbm  to  make  the 
yellow  pages  file  passwd.byname.  That  is,  the  key  is  a  username,  and  the  value  is  the  remaining 
line  in  the  /etc/passwd  file. 

SEE  ALSO 

dbm(3X),  newpasswd(8) 
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NAME 

MAKEDEV  —  make  system  special  files 
SYNOPSIS 

/dev/MAKEDEV  device,,, 

DESCRIPTION 

MAKEDEV  is  a  shell  script  normally  used  to  install  special  files.  It  resides  in  the  /dev  directory, 
as  this  is  the  normal  location  of  special  files.  Arguments  to  MAKEDEV  are  usually  of  the  form 
device-namel  where  device-name  is  one  of  the  supported  devices  listed  in  section  4  of  the 
manual  and  '?'  is  a  logical  unit  number  (0-9).  A  few  special  arguments  create  assorted  collections 
of  devices  and  are  listed  below. 

Btd  Create  the  standard  devices  for  the  system;  for  example,  /dev/console,  /dev/tty. 

local  Create  those  devices  specific  to  the  local  site.  This  request  runs  the  shell  file 
j  dev /MAKEDEV. local.  Site  specific  commands,  such  as  those  used  to  setup  dialup  lines 
as  ‘ttyd?’  should  be  included  in  this  file. 

Since  all  devices  are  created  using  mknod(S),  this  shell  script  is  useful  only  to  the  super-user. 
DIAGNOSTICS 

Either  self-explanatory,  or  generated  by  one  of  the  programs  called  from  the  script.  Use  sh  - 
X  MAKEDEV  in  case  of  trouble. 

SEE  ALSO 

intro(4),  config(8),  mknod(8) 
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NAME 

makekey  —  generate  encryption  key 

SYNOPSIS 

/usr/llb/makekey 

DESCRIPTION 

Makekey  improves  the  usefulness  of  encryption  schemes  depending  on  a  key  by  increasing  the 
amount  of  time  required  to  search  the  key  space.  It  reads  10  bytes  from  its  standard  input,  and 
writes  13  bytes  on  its  standard  output.  The  output  depends  on  the  input  in  a  way  intended  to  be 
difficult  to  compute  (that  is,  to  require  a  substantial  fraction  of  a  second). 

The  first  eight  input  bytes  (the  input  key)  can  be  arbitrary  ASCII  characters.  The  last  two  (the 
salt)  are  best  chosen  from  the  set  of  digits,  upper-  and  lower-case  letters,  and  and  '/’•  The  salt 
characters  are  repeated  as  the  first  two  characters  of  the  output.  The  remaining  11  output  char¬ 
acters  are  chosen  from  the  same  set  as  the  salt  and  constitute  the  output  key. 

The  transformation  performed  is  essentially  the  following:  the  salt  is  used  to  select  one  of  4096 
cryptographic  machines  all  based  on  the  National  Bureau  of  Standards  DES  algorithm,  but 
modified  in  4096  different  ways.  Using  the  input  key  as  key,  a  constant  string  is  fed  into  the 
machine  and  recirculated  a  number  of  times.  The  64  bits  that  come  out  are  distributed  into  the 
66  useful  key  bits  in  the  result. 

Makekey  is  intended  for  programs  that  perform  encryption  (for  instance,  ed  and  crj/p<(l)).  Usu¬ 
ally  makekey’s  input  and  output  will  be  pipes. 

SEE  ALSO 

crypt(l),  ed(l) 
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NAME 

mkfs  —  construct  a  file  system 
SYNOPSIS 

/etc/mkfB  special  size  |  nsect  j  [  ntrack  |  [  blksize  ]  }  fragsize  ]  [  ncpg  |  (  minfree  ]  ]  rps  ]  [  nbpi  | 
DESCRIPTION 

N.B.:  file  system  are  normally  created  with  the  nett)/s(8)  command. 

Mkfa  constructs  a  file  system  by  writing  on  the  special  file  apeeial.  The  numeric  size  specifies  the 
number  of  sectors  in  the  file  system.  Mkfa  builds  a  file  system  with  a  root  directory  and  a 
loat+found  directory  (see  /sci(8)).  The  number  of  i-nodes  is  calculated  as  a  function  of  the  file 
system  size.  No  boot  program  is  initialized  by  mkfa  (see  newfa{8)). 

OPTIONS 

The  optional  arguments  allow  fine  tune  control  over  the  parameters  of  the  file  system. 

Nsect  specify  the  number  of  sectors  per  track  on  the  disk. 

Ntrack 

specify  the  number  of  tracks  per  cylinder  on  the  disk. 

Blksize 

gives  the  primary  block  size  for  files  on  the  file  system.  It  must  be  a  power  of  two, 
currently  selected  from  4096  or  8192. 

Fragsize 

gives  the  fragment  size  for  files  on  the  file  system.  The  fragsize  represents  the  smallest 
amount  of  disk  space  that  will  be  allocated  to  a  file.  It  must  be  a  power  of  two  currently 
selected  from  the  range  512  to  8192. 

Ncpg  specifies  the  number  of  disk  cylinders  per  cylinder  group.  This  number  must  be  in  the 
range  1  to  32. 

Minfree 

specifies  the  minimum  percentage  of  free  disk  space  allowed.  Once  the  file  system  capa¬ 
city  reaches  this  threshold,  only  the  super-user  is  allowed  to  allocate  disk  blocks.  The 
default  value  is  10%. 

rpz  If  a  disk  does  not  revolve  at  60  revolutions  per  second,  this  parameter  may  be  specified. 

nbpi  Number  of  bytes  for  which  one  i-node  block  is  allocated.  This  parameter  is  currently  set 

at  one  i-node  block  for  every  2048  bytes. 

Users  with  special  demands  for  their  file  systems  are  referred  to  the  paper  cited  below  for  a  dis¬ 
cussion  of  the  tradeoffs  in  using  different  configurations. 

SEE  ALSO 

fs(5),  dir(5),  fsck(8),  newfs(8),  tunefs(8) 

McKusick,  Joy,  Leffler;  A  Faat  File  Syatem  for  Unix,  Syalem  Internala  Manual  for  the  Sun  Worka- 
tation. 


Sun  Release  2.0 


Last  change:  5  November  1984 


533 


MKN0D(8) 


MAINTENANCE  COMMANDS 


MKNOD(8) 


NAME 

mknod  —  build  special  file 


SYNOPSIS 

/etc/mknod  name 


c  ]  [  b  j  major  minor 


DESCRIPTION  j  .  u  •!>  *1. 

Mknod  makes  a  special  file.  The  first  argument  is  the  nome  of  the  entry.  The  second  is  b  if  the 

special  file  is  block-type  (disks,  tape)  or  c  if  it  is  character-type  (other  devices).  The  last  two 
arguments  are  numbers  specifying  the  major  device  type  and  the  minor  device  (for  example,  unit, 
drive,  or  line  number). 

Mknod  is  only  for  use  by  system  configuration  people.  Normally  you  should  use  fdeviMAKEDEV 
instead  when  making  special  files. 


SEE  ALSO 

mknod(2),  makedev(8) 
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NAME 

mkproto  —  construct  a  prototype  file  system 
SYNOPSIS 

/usr/etc/mkproto  special  proto 
DESCRIPTION 

Mkproto  is  used  to  bootstrap  a  new  file  system.  First  a  new  file  system  is  created  using  newf8{S), 
Mkproto  is  then  used  to  copy  files  from  the  old  file  system  into  the  new  file  system  according  to 
the  directions  found  in  the  prototype  file  proto.  The  prototype  file  contains  tokens  separated  by 
spaces  or  new  lines.  The  first  tokens  comprise  the  specification  for  the  root  directory.  File 
specifications  consist  of  tokens  giving  the  mode,  the  user-id,  the  group  id,  and  the  initial  contents 
of  the  file.  The  syntax  of  the  contents  field  depends  on  the  mode. 

The  mode  token  for  a  file  is  a  6  character  string.  The  first  character  specifies  the  type  of  the  file. 
(The  characters  —bed  specify  regular,  block  special,  character  special  and  directory  files  respec¬ 
tively.)  The  second  character  of  the  type  is  either  u  or  —  to  specify  set-user-id  mode  or  not.  The 
third  is  g  or  —  for  the  set-group-id  mode.  The  rest  of  the  mode  is  a  three  digit  octal  number 
giving  the  owner,  group,  and  other  read,  write,  execute  permissions,  see  cAmurf(l). 

Two  decimal  number  tokens  come  after  the  mode;  they  specify  the  user  and  group  ID’s  of  the 
owner  of  the  file. 

If  the  file  is  a  regular  file,  the  next  token  is  a  pathname  whence  the  contents  and  size  are  copied. 

If  the  file  is  a  block  or  character  special  file,  two  decimal  number  tokens  follow  which  give  the 
major  and  minor  device  numbers. 

If  the  file  is  a  directory,  mkproto  makes  the  entries  •  and  ••  and  then  reads  a  list  of  names  and 
(recursively)  file  specifications  for  the  entries  in  the  directory.  The  scan  is  terminated  with  the 
token  $. 

A  sample  prototype  specification  follows: 


d — 777  3  1 

usr  d — 

-777  3  1 

sh 

- 755  3  1  /bin/sh 

ken 

d — 755  6  1 

$ 

bO 

b — 644  3  1  0  0 

cO 

c — 644  3  1  0  0 

$ 

$ 

SEE  ALSO 

fs(5),  dir(5),  fsck(8),  newfs(8) 

BUGS 

There  should  be  some  way  to  specify  links. 

There  should  be  some  way  to  specify  bad  blocks. 

Mkproto  can  only  be  run  on  virgin  file  systems.  It  should  be  possible  to  copy  files  into  existent 
file  systems. 
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NAME 

monitor  —  system  PROM  monitor  and  command  interpreter 
SYNOPSIS 

Interrupt  UNIX  bootstrap  to  activate  command  interpreter  as  described  below. 

DESCRIPTION 

The  CPU  board  of  the  Sun  workstation  contains  a  set  of  PROMs  called  the  monitor,  which  con¬ 
trol  the  system  during  startup.  They  normally  test  the  system  then  search  for  and  attempt  to 
boot  UNIX.  However  if  you  interrupt  the  boot  procedure,  they  enter  interactive  mode  and 
accept  commands  interactively. 

To  enter  the  interactive  mode,  power  down  or  reset  the  system,  then  interrupt  the  UNIX 
bootstrap.  When  the  message: 

autoboot  in  progress 

appears,  enter  either: 

LI  -a  (press  LI,  then  a)  from  the  keyboard,  or 
BREL\K  (press  the  break  key)  from  a  terminal. 

The  monitor  displays  its  prompt: 

> 

COMMANDS 

The  list  of  monitor  commands  is  divided  into  two  sections;  miscellaneous  commands,  and  com¬ 
mands  to  open  and  examine  system  memory  resources.  These  are  clustered  at  the  end  because 
they  all  use  the  same  syntax. 

The  miscellaneous  commands  are: 

b|pa^^namej 

Boot.  By  itself,  b  searches  for  and  boots  UNIX;  when  followed  by  a  pathname,  it  boots 
the  specified  program,  b?  lists  the  possible  boot  devices. 

c\addr\  Continue  executing.  With  an  address,  it  executes  starting  there;  without  an  address,  it 
executes  starting  at  the  current  PC. 

%[addr\\pQram\ 

Start  program  execution.  Starts  executing  code  at  the  specified  address;  the  default  is 
the  current  PC. 

k[n«m5er] 

Reset.  The  default  is  0  which  resets  the  system  without  changing  memory  or  the  maps; 
1  resets  the  system  except  for  memory,  and  2  resets  the  entire  system  including  memory 
and  the  maps. 

B\number] 

Set  or  query  the  address  space  to  be  used  by  subsequent  access  commands,  number 
represents  the  function  code  to  be  used;  no  number  prints  the  current  function  code. 

u[det;][arp] 

Change  UART  assignment.  This  command  manipulates  the  on-board  UARTs  and 
switches  the  current  input  and  output  device.  It  accepts  the  following  devices: 

a-SIO-A 
b  —  SIO-B 
s  —  screen 
k  —  keyboard 
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And  the  following  arguments: 

I  —  input 
o  —  output 

#  (a  number)  —  UART  speed 
u  addr  —  Set  virtual  UART  address* 

The  commands  a,  d,  e,  1,  m,  o,  p,  and  r  open  various  system  resources  so  that  you  can  examine 
and  change  the  contents.  These  commands  all  use  the  following  syntax: 

c[addr|[a...j 

where: 

c  is  the  command 

addr  is  the  address  (in  hex)  or  the  register  number 

a  is  a  desired  action.  A  hex  number  means  "write  this  as  data";  any  non-hex  char¬ 
acter  means  "read  this  location" 

The  following  paragraphs  describe  these  commands: 

Open  A-register.  n  is  between  0  and  7,  0  starts  at  the  boundary  defined  by  the  command 
and  7  is  the  stack  pointer. 

Open  D-register,  n  is  0  to  7,  with  default  0. 
e[addr|[a...] 

Open  word  in  memory.  Default  address  is  0  as  set  by  the  command  Sy  and  odd  addresses 
are  rounded  down. 

l[arfdr][a...j 

Open  longword.  Opens  the  longword  at  the  address  addr]  the  default  is  0  in  the  address 
space  set  by  s,  and  odd  addresses  are  rounded  down. 

m 

Open  segment  map  entry  which  maps  virtual  address  addr  in  the  current  context. 
Current  e  command  setting  determines  supervisor  or  user  context.  (0-3  =  user;  4-7  ==5 
supervisor). 

o[addr][u...] 

Open  byte  location.  Opens  the  byte  at  the  specified  location;  the  default  is  0  in  the 
address  space  specified  by  s. 

Open  page  map  entry  which  maps  virtual  address  addr  in  the  current  context.  The 
default  is  0.  The  choice  of  context  is  determined  by  the  current  9  setting  (0-3  =  user;  4-7 
=  supervisor).  Displays  the  revelant  segment  map  entry  with  each  page  map  entry  in 
brackets, 

r|fldir][a...| 

Open  miscellaneous  registers,  as  follows: 

M  is  the  supervisor  stack  pointer 
UB  is  the  user  stack  pointer 

8f  is  the  source  function  code 

df  is  the  destination  function  code 

vb  is  the  vector  base 

8c  is  the  system  context 
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uc  is  the  user  context 

«p  is  the  status  register 

pc  is  the  program  counter. 

Changes  made  to  these  registers  (except  sc  and  vc)  do  not  take  effect  until  the  next  c  command. 
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NAME 

mount,  u mount  —  mount  and  dismount  filesystems 

SYNOPSIS 

/etc/mount 
/etc/mount  — p 
/etc/mount  — a[fv][t  type  ] 

/etc/mount  [  — frv][tQ  type  options  j  [  fsname  ]  [  dir  | 

/etc/umount  |  — av  |  |  fsname  |  dir  | 

DESCRIPTION 

Mount  announces  to  the  system  that  a  filesystem  fsname  is  to  be  attached  to  the  file  tree  at  the 
directory  dir.  The  directory  dir  must  already  exist.  It  becomes  the  name  of  the  newly  mounted 
root.  The  contents  of  dir  are  hidden  until  the  filesystem  is  unmounted.  If  fsname  is  of  the  form 
host:path  the  filesystem  type  is  assumed  to  be  n/s(4). 

Umount  announces  to  the  system  that  the  filesystem  fsname  previously  mounted  on  directory  dir 
should  be  removed.  Either  the  filesystem  name  or  the  mounted-on  directory  may  be  used. 

Mount  and  umount  maintain  a  table  of  mounted  filesystems  in  /etcfmtabj  described  in  m^a6(5). 
If  invoked  without  an  argument,  mount  displays  the  table.  If  invoked  with  only  one  ot  fsname  or 
dir  mount  searches  /etcffstab  for  an  entry  whose  dir  or  fsname  field  matches  the  given  argument. 
For  example, 

mount  /usr 

and 

mount  /dev/xyOg 
are  shorthand  for 

mount  /dev/xyOg  /usr 
if  this  line  is  in  fetc/fstab 

/dev/xyOg  /usr  4.2  rw  1  1 

MOUNT  OPTIONS 

—a  Attempt  to  mount  all  the  filesystems  described  in  fetc/fstab.  In  this  case,  fsname  and 
dir  are  taken  from  fetc/fstab.  If  a  type  is  specified  all  of  the  filesystems  in  fetc/fstab 
with  that  type  will  be  mounted. 

— o  The  next  argument  is  a  string  that  specifies  mount  options.  Valid  options  are:  ro,  rw, 

quota,  noquota,  hard,  soft.  Hard  and  soft  only  make  sense  on  n/s(4)  filesystems.  Options 
are  separated  by  commas.  The  options  ro  and  rw  stand  for  read-only  and  read-write;  rw 
is  the  default.  Since  quotas  are  not  implemented,  noguota  is  the  default.  With  a  hard 
remote  mount,  mount  tries  forever  if  the  mountd{Sc)  server  does  not  respond.  Once  the 
filesystem  is  mounted,  access  requests  will  retry  forever  if  the  nfsd{S)  server  does  not 
respond.  Hard  is  the  default.  With  a  soft  remote  mount,  if  the  mountd{%c)  server  does 
not  respond,  mount  forks  a  background  copy  to  retry  forever.  Once  the  soft  mount  com¬ 
pletes,  access  requests  will  fail  with  (ETIMEDOUT]  if  the  nfsd[S)  server  does  not  respond. 

— r  Mount  the  specified  filesystem  read-only.  This  is  a  shorthand  for: 

mount  — o  ro  fsname  dir 

Physically  write-protected  and  magnetic  tape  filesystems  must  be  mounted  read-only,  or 
errors  will  occur  when  access  times  are  updated,  whether  or  not  any  explicit  write  is 
attempted. 

— t  The  next  argument  is  the  filesystem  type.  The  accepted  types  are:  4.2,  nfs,  and  pc;  see 
fstab{b)  for  a  description  of  the  legal  filesystem  types. 

— f  Fake  a  new  fetcfmtab  entry,  but  do  not  actually  mount  any  filesystems. 

— p  Print  the  list  of  mounted  filesystems  in  a  format  suitable  for  use  in  fetc/fstab, 

—V  Verbose  —  mount  displays  a  message  indicating  the  filesystem  being  mounted. 
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UMOUNT  OPTIONS 

—a  Attempt  to  unmount  all  the  filesystems  currently  mounted.  In  this  case,  fename  is  taken 
from  fetclmtab. 

—V  Verbose  —  umount  displays  a  message  indicating  the  filesystem  being  unmounted. 


EXAMPLES 

mount  /dev/xyOg  /usr 
mount  —ft  4.2  /dev/ndO  / 
mount  —at  4,2 

mount  -t  nfs  serv;/usr/src  /usr/src 
mount  serv:/usr/src  /usr/src 
mount  -o  hard  serv;/usr/src  /usr/src 
mount  — p  >  /etc/fstab 


mount  a  local  disk 
fake  an  entry  for  nd  root 
mount  all  4.2  filesystems 
mount  remote  filesystem 
same  as  above 

same  as  above  but  hard  mount 
save  current  mount  state 


FILES 

/etc/mtab  mount  table 

/etc/fstab  filesystem  table 


SEE  ALSO 

mount(2),  nfsmount(2),  unmount(2),  fstab(5),  mountd(8c),  nfsd(8c) 


BUGS 

Mounting  filesystems  full  of  garbage  will  crash  the  system. 

No  more  than  one  user  should  mount  a  disk  partition  "read*write  or  the  file  system  may  become 
corrupted. 
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NAME 

mountd  —  NFS  mount  request  server 
SYNOPSIS 

/usr  /etc/rpe.mountd 
DESCRIPTION 

Mountd  is  an  rpc(4)  server  that  answers  file  system  mount  requests.  It  reads  the  file 
/etc/exports,  described  in  exporters),  to  determine  which  file  systems  are  available  to  which 
machines  and  users.  It  also  provides  information  as  to  which  clients  have  file  systems  mounted. 
This  information  can  be  printed  using  the  sAoa;mnttnt(8)  command. 

The  mountd  daemon  is  normally  invoked  by  »neId(8C). 

SEE  ALSO 

nfs(4),  rpc(4),  exports(6),  services(5),  inetd(8),  showmount(8) 
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NAME 

ncheck  —  generate  names  from  i-numbers 
SYNOPSIS 

/uBr/etc/neheek  [  —1  nam6er«  {  [  —a  ]  |  — ■  |  [  fileaystem  ] 

DESCRIPTION 

N.B.:  For  most  normal  file  system  maintenance,  the  function  of  ncheck  is  subsumed  by  fsck{S)» 

Ncheck  with  no  argument  generates  a  pathname  versus  i-number  list  of  all  files  on  a  set  of 
default  file  systems.  Names  of  directory  files  are  followed  by  */•*. 

A  file  system  may  be  specified  by  the  optional  fileeystem  argument. 

The  report  is  in  no  useful  order,  and  probably  should  be  sorted, 

OPTIONS 

—I  numbers 

Report  only  those  files  whose  i-numbers  follow, 

—a  Print  the  names  and  ‘a*’,  which  are  ordinarily  suppressed. 

“8  Report  only  special  files  and  files  with  set-user-ID  mode.  This  is  intended  to  discover 
concealed  violations  of  security  policy. 

SEE  ALSO 

sort(l),  dcheck(8),  fsck(8),  icheck(8) 

DIAGNOSTICS 

When  the  filesystem  structure  is  improper,  denotes  the  ‘parent’  of  a  parentless  file  and  a 
pathname  beginning  with  denotes  a  loop. 
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NAME 

nd  —  network  disk  control 

SYNOPSIS 

/ctc/nd  I  command  j 

DESCRIPTION 

The  nd  command  controls  the  network  disk  service  of  the  kernel  as  described  in  nd(4p).  A  single 
command  may  be  given  on  the  command  line;  if  none  is  given  then  the  standard  input  is  read  for 
a  list  of  commands.  Typically,  the  file  /etc/nd.local  is  used  for  input.  Lines  beginning  with 
are  considered  to  be  comments. 

The  available  commands  are: 

user  hostname  hisunit  mydev  myoff  mysize  mylunit 

For  the  client  hostname  transform  incoming  requests  for  hisunit  into  server  device  mydev 
at  offset  myoff  and  size  mysize  sectors,  /dey/ndlmylunit  provides  a  local  name  for  this 
disk  "subpartition".  If  mysize  is  "-1",  then  this  user  unit  is  equivalent  to  the  entire 
filesystem  partition  mydev  (no  "subpartioning"  is  done.)  If  mylunit  is  "-1"  then  no  local 
name  is  needed  for  this  user  unit;  this  is  usually  the  case  with  a  swap  unit,  or  a  unit 
represented  by  an  entire  filesystem.  If  hostname  is  a  numeric  zero,  hisunit  refers  to  a 
public  unit. 

ether  hostname  eiher^addr  {  maxpacks  ] 

The  ether  command  associates  an  Ethernet  address  ether_addr  yfith.  the  client  hostname. 
This  information  is  required  in  order  for  a  client  to  learn  his  Internet  address  when  it 
boots  -  nd  provides  the  Internet  address  for  hostname  based  on  the  Ethernet  address 
received  in  a  boot  request.  The  Ethernet  address  is  given  as  size  hex  bytes  separated  by 
colons,  e.g.,  8:0:20:l:l:a3.  At  least  one  previous  user  command  must  have  been  issued 
for  the  client.  The  maxpacks  option  may  be  given  to  set  the  maximum  number  of  pack¬ 
ets  that  the  server  will  send  to  the  client  before  requesting  an  acknowledge.  The  default 
is  6;  it  should  suffice  unless  the  client  Ethernet  interface  is  very  slow. 

version  versionnumher 

The  version  command  gives  the  level  of  configuration  of  the  server.  Occasionally  the 
need  arises  to  reorganize  or  reload  the  diskless  partitions.  Since  the  clients  will  rewrite 
locally  cached  blocks,  they  must  be  kept  from  writing  their  filesystems  until  they  reboot. 
Before  such  a  reorganization  occurs,  the  system  manager  should  warn  diskless  users  to 
save  files  and  halt  their  machines.  Modification  of  the  partitions  should  occur  with  the 
disk  server  off.  After  modification  is  complete,  versionnumher  should  be  incremented  to 
force  users  to  reboot. 

son 

Starts  the  network  disk  server.  This  command  should  be  issued  after  all  user,  ether, 
and  version  commands. 

BOff 

Stops  the  disk  server  until  a  subsequent  son  command. 

clear 

Stops  the  disk  server  and  clears  all  user  and  ether  information, 
serverat  hostname 

Systems  with  disks  may  use  the  serverat  command  to  specify  a  disk  server  if  they  wish 
to  user  a  network  disk  in  addition  to  their  locally  attached  disk.  Even  then,  this  com¬ 
mand  is  only  necessary  if  they  wish  to  use  a  public  network  disk  or  if  they  wish  to  change 
network  disk  servers. 
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FILES 

/etc/nd.local 

SEE  ALSO 

nd(4p) 

BUGS 

No  sanity  checking  of  disk  partitions  is  done. 
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NAME 

netstat  —  show  network  status 
SYNOPSIS 

netstat  |  -in|-i[  -h|-r  |  [  -a  j  [  -n  ]  [  -s  |  [  -t  j  [  -A  [  [  interval  |  |  ayetem  \  [  core  ] 
DESCRIPTION 

Netstat  symbolically  displays  the  contents  of  various  network-related  data  structures. 

The  arguments,  system  and  core  allow  substitutes  for  the  defaults  ‘/vmunix’  and  ^/dey/kmem\ 

If  an  interval  is  specified,  netstat  continuously  displays  the  information  regarding  packet  traffic  on 
the  configured  network  interfaces,  pausing  interval  seconds  before  refreshing  the  screen. 

There  are  a  number  of  display  formats,  depending  on  the  information  that  netstat  presents.  The 
display  formats  are  controlled  by  the  options  listed  below  and  are  described  there. 

OPTIONS 

Not  all  of  the  options  listed  here  can  be  used  in  combination.  Some  of  the  options  select  the 
information  to  be  displayed,  and  some  of  the  options  further  qualify  that  specific  display.  Netstat 
checks  its  options  in  the  order  — m  (memory  management  statistics),  —1  (interface  statistics),  — h 
(host  table  state),  and  — r  (routing  tables),  and  presents  a  display  for  only  one  of  these  options. 

The  default  display,  for  active  sockets,  shows  the  local  and  remote  addresses,  send  and  receive 
queue  sizes  (in  bytes),  protocol,  and,  optionally,  the  internal  state  of  the  protocol.  Other  display 
formats  are  controlled  by  the  options  listed  below. 

— m  Show  statistics  recorded  by  the  memory  management  routines  (the  network  manages  a 
‘"private  share”  of  memory) 

— i  Show  the  state  of  interfaces  which  have  been  auto-configured  (interfaces  statically 
configured  into  a  system,  but  not  located  at  boot  time  are  not  shown)  The  interface 
display  provides  a  table  of  cumulative  statistics  regarding  packets  transferred,  errors, 
and  collisions.  The  network  address  (currently  Internet  specific)  of  the  interface  and  the 
maximum  transmission  unit  (“mtu”)  are  also  displayed. 

— h  Show  the  state  of  the  IMP  host  table.  This  does  not  work  in  an  environment  where  the 

IMP  host  tables  do  not  exist. 

— r  Show  the  routing  tables.  The  routing  table  display  indicates  the  available  routes  and 

their  status.  Each  route  consists  of  a  destination  host  or  network  and  a  gateway  to  use 
in  forwarding  packets.  The  flags  field  shows  the  state  of  the  route  (“U”  if  ”up”),  and 
whether  the  route  is  to  a  gateway  (“G”).  Direct  routes  are  created  for  each  interface 
attached  to  the  local  host.  The  refent  field  gives  the  current  number  of  active  uses  of 
the  route.  Connection  oriented  protocols  normally  hold  on  to  a  single  route  for  the  dura¬ 
tion  of  a  connection  while  connectionless  protocols  obtain  a  route  then  discard  it.  The 
use  field  provides  a  count  of  the  number  of  packets  sent  using  that  route.  The  interface 
entry  indicates  the  network  interface  utilized  for  the  route. 

Options  listed  below  provide  further  qualification  for  the  display  formats  listed  above, 

—A  Show  the  address  of  any  associated  protocol  control  blocks;  used  for  debugging. 

—a  Show  the  state  of  all  sockets;  normally  sockets  used  by  server  processes  are  not  shown 

— n  Show  network  addresses  as  numbers  (normally  netstat  interprets  addresses  and  attempts 

to  display  them  symbolically). 

— B  Show  per-protocol  statistics.  When  used  with  the  — r  option,  the  — s  option  displays 

routing  statistics. 

— t  Add  timer  information  to  the  interface  display. 
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FURTHER  NOTES 

Address  formats  are  of  the  form  “host.port"  or  “network.port”  if  a  socket’s  address  specifies  a 
network  but  no  specific  host  address.  When  known  the  host  and  network  addresses  are  displayed 
symbolically  according  to  the  data  bases  feie/hosts  and  {etc! networks,  respectively.  If  a  sym¬ 
bolic  name  for  an  address  is  unknown,  or  if  the  — n  option  is  specified,  the  address  is  printed  in 
the  Internet  “dot  format”;  refer  to  »ne<(3N)  for  more  information  regarding  this  format. 
Unspecified,  or  “wildcard”,  addresses  and  ports  appear  as 

When  netstat  is  invoked  with  an  interval  argument,  it  displays  a  running  count  of  statistics 
related  to  network  interfaces.  This  display  consists  of  a  column  summarizing  information  for  all 
interfaces,  and  a  column  for  the  interface  with  the  most  traffic  since  the  system  was  last 
rebooted.  Every  24th  line  of  each  screen  of  information  contains  a  summary  since  the  system 
was  last  rebooted.  Subsequent  lines  of  output  show  values  accumulated  over  the  preceding  inter¬ 
val. 

SEE  ALSO 

iostat(8),  vmstat(8),  hosts(5),  networks(5),  protocols(5),  serviccs(5),  trpt(8C) 

BUGS 

The  notion  of  errors  is  ill-defined.  Collisions  mean  something  else  for  the  IMP. 

The  kernel’s  tables  can  change  while  netstat  is  examining  them,  creating  incorrect  or  partial 
displays. 
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NAME 

newaliases  —  rebuild  the  data  base  for  the  mail  aliases  file 

SYNOPSIS 

newaliases 

DESCRIPTION 

Newaliases  rebuilds  the  random  access  data  base  for  the  mail  aliases  file  /usrf lib/ aliases.  It 
must  be  run  each  time  /usr/ lib/ aliases  is  changed  in  order  for  the  change  to  take  effect. 

SEE  ALSO 

aliases(5),  sendmail(8) 
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NAME 

newfs  —  construct  a  new  file  system 
SYNOPSIS 

/etc/newfs  |  -v  |  [  -n  j  [  mkfs-optionB  [  special  [  disk-type  ] 

DESCRIPTION 

Ntwfs  is  a  “friendly’*  front-end  to  the  mkfa{S)  program.  On  the  VAX,  newfs  will  look  up  the 
type  of  disk  a  file  system  is  being  created  on  in  the  disk  description  file  /etc/disktab;  on  the  Sun 
the  disk  type  is  determined  by  reading  the  disk  label.  Newfs  then  calculates  the  appropriate 
parameters  to  use  in  calling  mkfs,  then  builds  the  file  system  by  forking  mkfs  and,  if  the  file  sys¬ 
tem  is  a  root  partition,  installs  the  necessary  bootstrap  programs  in  the  initial  16  sectors  of  the 
device. 

OPTIONS 

— n  Do  not  install  the  bootstrap  programs. 

—v  newfs  prints  out  its  actions,  including  the  parameters  passed  to  mkfs. 

Options  which  may  be  used  to  override  default  parameters  passed  to  mkfs  are: 

— s  size  The  size  of  the  file  system  in  sectors. 

— b  block-size 

The  block  size  of  the  file  system  in  bytes. 

— f  fk^ag-size 

The  fragment  size  of  the  file  system  in  bytes, 

— t  #t racks/cylinder 
— c  #ey  Under  s/group 

The  number  of  cylinders  per  cylinder  group  in  a  file  system.  The  default  value  used  is 
16. 

— m  free  space  % 

The  percentage  of  space  reserved  from  normal  users;  the  minimum  free  space  thresh- 
hold.  The  default  value  used  is  10%. 

—r  revolutions/mlnute 

The  speed  of  the  disk  in  revolutions  per  minute  (normally  3600). 

FILES 

/etc/disktab  for  disk  geometry  and  file  partition  information  (VAX  only) 

/etc/mkfs  to  actually  build  the  file  system 
/usr/mdec  for  boot  strapping  programs 

SEE  ALSO 

fs(5),  fsck(8),  tunefs(8) 

The  Sun  UNIX  FUe  System  in  the  Sun  System  Internals  Manual. 
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NAME 

nfsd,  Mod  —  NFS  daemons 

SYNOPSIS 

/etc/nfsd  |  nservers  ] 

/etc/biod  [  nservers  | 

DESCRIPTION 

Nf$d  starts  the  nfe{4)  server  daemons  that  handle  client  filesystem  requests.  Naervera  is  the 
number  of  file  system  request  daemons  to  start.  This  number  should  be  based  on  the  load 
expected  on  this  server;  four  is  a  good  number.  If  neervera  is  not  specified  it  defaults  to  one. 

Btod  starts  nservers  asynchronous  block  I/O  daemons.  This  command  is  used  on  a  NFS  client  to 
handle  read-ahead  and  write-behind  of  buffer  cached  blocks.  A  good  value  for  nservers  is  four;  if 
not  specified  it  defaults  to  one. 

SEE  ALSO 

nfs(4),  rpc(4),  mountd(8c),  exports(S) 
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NAME 

nfsstat  —  Network  File  System  statistics 

SYNOPSIS 

nfsstat  I  — csnrds  j 

DESCRIPTION 

Nfsstat  displays  statistical  information  about  the  Network  File  System  (NFS),  Remote  Procedure 
Call  (RPC),  and  Network  Disk  (ND)  interfaces  to  the  kernel.  It  can  also  be  used  to  reinitialize 
this  information.  If  no  options  are  given  the  default  is 

nfsstat  — csnr 

That  is,  print  everything  except  ND  information,  and  reinitialize  nothing. 

OPTIONS 

— c  Display  client  information.  Only  the  client  side  NFS  and  RPC  information  will  be 

printed.  Can  be  combined  with  the  — n  and  — r  options  to  print  client  NFS  or  client 
RPC  information  only. 

— s  Display  server  information.  Works  like  the  — c  option  above. 

— n  Display  NFS  information.  NFS  information  for  both  the  client  and  server  side  will  be 

printed.  Can  be  combined  with  the  — c  and  — ■  options  to  print  client  or  server  NFS 
information  only. 

-r  Display  RPC  information.  Works  like  the  -n  option  above. 

— d  Display  Network  Disk  (ND)  information. 

— *  Zero  (reinitialize)  statistics.  Can  be  combined  with  any  of  the  above  options  to  zero  par¬ 
ticular  sets  of  statistics  after  printing  them.  The  user  must  have  write  permission  on 
fdev/kmem  for  this  option  to  work. 

FILES 

/vmunix  system  namelist 
/dev/kmem  kernel  memory 

SEE  ALSO 

nfs(4) 
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NAME 

pac  —  print er/p!otter  accounting  information 
SYNOPSIS 

/usr/etc/pac  |  —Fprinter  |  [  — ppnce  j  [  — b  |  [  — r  |  [  — c  |  ]  name  ...  [ 

DESCRIPTION 

Pac  reads  the  printer/plotter  accounting  files,  accumulating  the  number  of  pages  (the  usual  case) 
or  feet  (for  raster  devices)  of  paper  consumed  by  each  user,  and  printing  out  how  much  each  user 
consumed  in  pages  or  feet  and  dollars.  If  any  names  are  specified,  then  statistics  are  only  printed 
for  those  users;  usually,  statistics  are  printed  for  every  user  who  has  used  any  paper. 

OPTIONS 

—Vprinter 

Do  accounting  for  the  named  printer.  Normally,  accounting  is  done  for  the  default 
printer  (site  dependent)  or  the  value  of  the  PRINTER  environment  variable  is  used. 

--p  price 

Use  the  value  price  for  the  cost  in  dollars  instead  of  the  default  value  of  0.02. 

— c  Sorted  the  output  by  cost;  usually  the  output  is  sorted  alphabetically  by  name. 

— r  Reverse  the  sorting  order. 

— B  Summarize  the  accounting  information  on  the  summary  accounting  file;  this  summary  is 

necessary  since  on  a  busy  system,  the  accounting  file  can  grow  by  several  lines  per  day. 

FILES 

/usr/adm/?acct  raw  accounting  files 

/usr/adm/?^um  summary  accounting  files 

BUGS 

The  relationship  between  the  computed  price  and  reality  is  as  yet  unknown. 
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NAME 

ping  —  network  debugging 
SYNOPSIS 

/usr/etc/ping  host  |  timeout  j 
DESCRIPTION 

Ping  repeatedly  sends  an  icmp  echo  packet  to  host  and  reports  whether  or  not  a  reply  was 
received.  It  keeps  trying  until  timeout  seconds  have  elapsed,  or  an  answer  is  received.  The 
default  timeout  is  20  seconds.  The  host  argument  can  be  a  name  or  an  internet  address. 

SEE  ALSO 

icmp(4P} 
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NAME 

portmap  —  DARPA  port  to  RPC  program  number  mapper 
SYNOPSIS 

/uar/etc/rpe.portmap 

DESCRIPTION 

Portmap  is  a  server  that  converts  RPC  program  numbers  into  DARPA  protocol  port  numbers.  It 
must  be  running  in  order  to  make  RPC  calls. 

When  an  RPC  server  is  started,  it  will  tell  portmap  what  port  number  it  is  listening  to,  and  what 
RPC  program  numbers  it  is  prepared  to  serve.  When  a  client  wishes  to  make  an  RPC  call  to  a 
given  program  number,  it  will  first  contact  portmap  on  the  server  machine  to  determine  the  port 
number  where  RPC  packets  should  be  sent. 

Normally,  standard  RPC  servers  are  started  by  »nelrf(8c),  so  portmap  must  be  started  before 
inetd  is  invoked. 

SEE  ALSO 

servers(5),  rpcinfo(8),  inetd(8) 

BUGS 

If  portmap  crashes,  ail  servers  must  be  restarted. 
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NAME 

pstat  —  print  system  facts 


SYNOPSIS 

/etc/pstat  — aixptufT  |  subopHont  |  |  system  [  eorefile  { ] 


DESCRIPTION 

Pstat  interprets  the  contents  of  certain  system  tables.  If  corefile  is  given,  the  tables  are  sought 
there,  otherwise  in  fdev/kmem.  The  required  namelist  is  taken  from  /vmunix  unless  system  is 
specified. 


OPTIONS 

—a  Under  — p,  describe  all  process  slots  rather  than  just  active  ones. 


—I  Print  the  inode  table  including  the  associated  vnode  entries  with  these  headings: 


LOC 

IFLAG 


IDEVICE 

INO 

MODE 

NLK 

UID 

SIZE/DEV 

VFLAG 


CNT 

SHC 

EXC 

TYPE 


The  core  location  of  this  table  entry. 

Miscellaneous  inode  state  variables  encoded  thus: 

A  inode  access  time  must  be  corrected 
C  inode  has  been  changed 

L  inode  is  locked 

R  inode  is  being  referenced 

T  inode  contains  a  pure  text  prototype 

U  update  time  (/s(5))  must  be  corrected 
W  wanted  by  another  process  (L  flag  is  on) 

Z  someone  waiting  for  an  exclusive  lock 

Major  and  minor  device  number  of  file  system  in  which  this  inode  resides. 
I-number  within  the  device. 

Mode  bits  in  octal,  see  chmod{2). 

Number  of  links  to  this  inode. 

User  ID  of  owner. 

Number  of  bytes  in  an  ordinary  file,  or  major  and  minor  device  of  special  file. 
Miscellaneous  vnode  state  variables  encoded  thus: 

R  root  of  its  file  system 

S  shared  lock  applied 

E  exclusive  lock  applied 

T  vnode  is  a  pure  text  prototype 

Z  proccess  is  waiting  for  a  shared  or  exclusive  lock 
Number  of  open  file  table  entries  for  this  vnode. 

Reference  count  of  shared  locks  on  the  vnode. 

Reference  count  of  exclusive  locks  on  the  vnode  (this  may  be  >  1  if,  for  exam¬ 
ple,  a  file  descriptor  is  inherited  across  a  fork). 

Vnode  file  type,  either  VNON  (no  type),  VREG  (regular),  VDIR  (directory), 
VBLK  (block  device),  VCHR  (character  device),  VLNK  (symbolic  link),  VSOC 
(socket),  or  VBAD  (bad). 


— X  Print  the  text  table  with  these  headings: 

LOC  The  core  location  of  this  table  entry. 

FLAGS  Miscellaneous  state  variables  encoded  thus: 

P  resulted  from  demand- page- from-i node  exec  format  (see  execve{2)) 
T  ptrace{2)  in  effect 
W  text  not  yet  written  on  swap  device 
L  loading  in  progress 
K  locked 

w  wanted  (L  flag  is  on) 
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DADDR  Disk  address  in  swap,  measured  in  multiples  of  612  bytes, 

CADDR  Head  of  a  linked  list  of  loaded  processes  using  this  text  segment. 

RSS  Resident  set  size,  measured  in  multiples  of  512  bytes. 

SIZE  Size  of  text  segment,  measured  in  multiples  of  512  bytes, 

VPTR  Core  location  of  corresponding  vnode. 

CNT  Number  of  processes  using  this  text  segment. 

CCNT  Number  of  processes  in  core  using  this  text  segment. 

-*p  Print  process  table  for  active  processes  with  these  headings: 

LOC  The  core  location  of  this  table  entry. 

S  Run  state  encoded  thus: 

0  no  process 

1  awaiting  an  event 

2  (abandoned  state) 

3  runnable 

4  being  created 

6  being  terminated 

6  stopped  under  trace 

F  Miscellaneous  state  variables,  or-ed  together  (hexadecimal): 

0000001  loaded 

0000002  a  system  process  (scheduler  or  page-out  daemon) 

0000004  locked  for  swap  out 

0000008  swapped  out  during  process  creation 

0000010  traced 

0000020  used  in  tracing 

0000040  user  settable  lock  in  core 

0000080  in  page-wait 

0000100  prevented  from  swapping  during  fork{2) 

0000200  restore  old  sigmask  after  taking  signal 

0000400  exiting 

0000800  doing  physical  i/o 

0001000  process  resulted  from  a  vfork(2)  which  is  not  yet  complete 
0002000  another  flag  for  vfork{2) 

0004000  process  has  no  virtual  memory,  as  it  is  a  parent  in  the  context  of 
vfork{2) 

0008000  process  is  demand  paging  data  pages  from  its  text  inode 
0010000  process  has  advised  of  sequential  behavior  with  vadvt$e{2) 

0020000  process  has  advised  of  anomalous  behavior  with  vadvi9c{2) 

0040000  process  is  in  a  sleep  which  will  timeout 
0080000  (unused) 

0100000  using  old  signal  mechanism 
0200000  process  is  owed  a  profiling  tick 
0400000  process  is  setting  up  a  8elect{2)  call 
0800000  Process  is  a  login  process 

1000000  Page  tables  for  this  process  have  changed  (tlb  is  dirty) 

POIP  number  of  pages  currently  being  pushed  out  from  this  process. 

PRI  Scheduling  priority,  see  9etpriority{2). 

SIG  Signals  received  (signals  1-32  coded  in  bits  0-31), 

UID  Real  user  ID, 

SLP  Amount  of  time  process  has  been  blocked. 
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TIM  Time  resident  in  seconds;  times  over  127  coded  as  127. 

CPU  Weighted  integral  of  CPU  time,  for  scheduler. 

NI  Nice  level,  see  8etpriority{2), 

PGRP  Process  number  of  root  of  process  group  (the  opener  of  the  controlling  terminal). 
PID  The  process  ED  number. 

PPID  The  process  ID  of  parent  process. 

ADDR  If  in  core,  the  page  frame  number  of  the  first  page  of  the  'u-area’  of  the  process. 

If  swapped  out,  the  position  in  the  swap  area  measured  in  multiples  of  612  bytes. 
RSS  Resident  set  size  —  the  number  of  physical  page  frames  allocated  to  this  process. 
SRSS  RSS  at  last  swap  (0  if  never  swapped). 

SIZE  Virtual  size  of  process  image  (data+stack)  in  multiples  of  612  bytes. 

WCHAN  Wait  channel  number  of  a  waiting  process. 

LINK  Link  pointer  in  list  of  runnable  processes. 

TEXT?  If  text  is  pure,  pointer  to  location  of  text  table  entry. 

CLKT  Countdown  for  real  interval  timer,  8€titim€r{2)  measured  in  clock  ticks  (10  mil¬ 
liseconds). 

— t  Print  table  for  terminals  with  these  headings: 

RAW  Number  of  characters  in  raw  input  queue. 

CAN  Number  of  characters  in  canonicalized  input  queue. 

OUT  Number  of  characters  in  putput  queue. 

MODE  See  «y(4). 

ADDR  Physical  device  address. 

DEL  Number  of  delimiters  (newlines)  in  canonicalized  input  queue. 

COL  Calculated  column  position  of  terminal. 

STATE  Miscellaneous  state  variables  encoded  thus: 

T  delay  timout  in  progress 

W  waiting  for  open  to  complete 

O  open 

C  carrier  is  on 

B  busy  doing  output 

A  process  is  awaiting  output 

X  open  for  exclusive  use 
H  hangup  on  close 

PGRP  Process  group  for  which  this  is  controlling  terminal. 

DISC  Line  discipline;  blank  is  old  tty  OTTYDISC  or  ‘^new  tty”  for  NTTYDISC  or  “net” 
for  NETLDISC  (see  bk{4)). 

— u  print  information  about  a  user  process;  the  next  argument  is  its  address  as  given  by  p^(l). 
The  process  must  be  in  main  memory,  or  the  file  used  can  be  a  core  image  and  the  address 
0. 

— f  Print  the  open  file  table  with  these  headings: 

LOC  The  core  location  of  this  table  entry. 

TYPE  The  type  of  object  the  file  table  entry  points  to. 

FLG  Miscellaneous  state  variables  encoded  thus: 

R  open  for  reading 

W  open  for  writing 

A  open  for  appending 

S  shared  lock  present 

X  exclusive  lock  present 
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I  signal  pgrp  when  data  ready 
CNT  Number  of  processes  that  know  this  open  file. 

MSG  Number  of  references  from  message  queue. 

DATA  The  location  of  the  vnode  table  entry  or  socket  for  this  file. 

OFFSET  The  file  offset  (see  l9eek{2))^  or  the  core  address  of  the  associated  socket  struc¬ 
ture. 

— •  print  information  about  swap  space  usage:  the  number  of  (512  byte)  blocks  used  and  free  is 
given  as  well  as  the  number  of  used  blocks  which  belong  to  text  images. 


— T  prints  the  number  of  used  and  free  slots  in  the  several  system  tables  and  is  useful  for  check¬ 
ing  to  see  how  full  system  tables  have  become  if  the  system  is  under  heavy  load. 

FILES 

/vmunix  namelist 
/dev/kmem  default  source  of  tables 

SEE  ALSO 

p5(l),  5tat(2),  fs(5) 

K.  Thompson,  UNIX  Implementation 

BUGS 

It  would  be  very  useful  if  the  system  recorded  “maximum  occupancy”  on  the  tables  reported  by 
— T;  even  more  useful  if  these  tables  were  dynamically  allocated. 
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NAME 

quot  —  summarize  file  system  ownership 
SYNOPSIS 

/uar/etc/quot  [  — cfhnv  ]  (  fileBystem  ] 

DESCRIPTION 

Quoi  displays  the  number  of  blocks  (1024  bytes)  in  the  named  jHesyBitm  currently  owned  by  each 
user.  If  no  filesystem  is  named,  a  default  name  is  used. 

OPTIONS 

— c  Display  three  columns  giving  file  size  in  blocks,  number  of  files  of  that  size,  and  cumula¬ 

tive  total  of  blocks  in  that  size  or  smaller  file. 

— f  Display  count  of  number  of  files  as  well  as  space  owned  by  each  user. 

— h  Estimate  the  number  of  blocks  in  the  file  —  this  doesn’t  account  for  files  with  holes  in 

them. 

— n  Run  the  pipeline  ncheck  filesystem  {  sort  +0n  {  quot  — n  filesystem  to  produce  a  list 

of  ail  files  and  their  owners. 

—V  Display  three  columns  containing  the  number  of  blocks  not  accessed  in  the  last  30,  60, 
and  90  days. 

FILES 

Default  file  system  varies  with  system. 

/etc/passwd  to  get  user  names 

SEE  ALSO 

ls(l),  du(l) 


O 
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NAME 

rc  —  command  script  for  auto-reboot  and  daemons 

SYNOPSIS 

/etc/rc 

/etc/rc.local 

DESCRIPTION 

Rc  is  the  command  script  which  controls  the  automatic  reboot  and  rcJoeal  is  the  script  holding 
commands  which  are  pertinent  only  to  a  specific  site. 

When  an  automatic  reboot  is  in  progress,  rc  is  invoked  with  the  argument  autoboot  and  runs  a 
fsck  with  option  — p  to  “preen”  all  the  disks  of  minor  inconsistencies  resulting  from  the  last  sys¬ 
tem  shutdown  and  to  check  for  serious  inconsistencies  caused  by  hardware  or  software  failure.  If 
this  auto-check  and  repair  succeeds,  then  the  second  part  of  rc  is  run. 

The  second  part  of  rc,  which  is  run  after  a  auto-reboot  succeeds  and  also  if  rc  is  invoked  when  a 
single  user  shell  terminates  (see  mt7(8)),  starts  all  the  daemons  on  the  system,  preserves  editor 
files  and  clears  the  scratch  directory  /tmp.  RcJocal  is  executed  immediately  before  any  other 
commands  after  a  successful  fsck.  Normally,  the  first  commands  placed  in  the  rc.local  file  define 
the  machine’s  name,  using  /jos^name(l),  and  save  any  possible  core  image  that  might  have  been 
generated  as  a  result  of  a  system  crash,  8avtcort{f^>),  The  latter  coinmand  is  included  in  the 
rcJocal  file  because  the  directory  in  which  core  dumps  are  saved  is  usually  site  specific. 

SEE  ALSO 

init(8),  reboot(8),  savecore(8) 
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NAME 

rdatc  —  set  system  date  from  a  remote  host 
SYNOPSIS 

/uBf/ucb/rdate  hostname 
DESCRIPTION 

Rdate  sets  the  local  date  and  time  from  the  hoetname  given  as  argument.  You  must  be  super- 
user  on  the  local  system.  Typically  rdate  can  be  inserted  as  part  of  y_our  /e/c/rc./oco/  startup 
script. 

SEE  ALSO 

timed(8C) 

BUGS 

Could  be  modified  to  accept  a  list  of  hostnames  and  try  each  until  a  valid  date  returned.  Better 
yet  would  be  to  write  a  real  date  server  that  accepted  broadcast  requests. 
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NAME 

reboot  —  UNIX  bootstrapping  procedures 
SYNOPSIS 

/etc/reboot  [  — n  j  [  — q  ] 

DESCRIPTION 

The  UNIX  operating  system  is  started  by  placing  it  in  memory  transferring  to  it.  Since  the  sys¬ 
tem  is  not  re-enterable,  it  is  necessary  to  read  it  in  from  disk  or  tape  each  time  it  is  to  be 
bootstrapped. 

Rebooting  a  running  system.  When  a  UNIX  system  is  running  and  a  reboot  is  desired,  ekui- 
dou;n(8)  is  normally  used.  If  there  are  no  users  then  /etc/rcboot  can  be  used.  Reboot  performs 
a  sync  operation  on  the  disks,  and  then  a  multi-user  reboot  (as  described  below)  is  initiated.  This 
causes  a  system  to  be  booted  and  an  automatic  disk  check  to  be  performed.  If  all  this  succeeds 
without  incident,  the  system  is  then  brought  up  multi-user. 

OPTIONS 

— n  option  avoids  the  sync.  It  can  be  used  if  a  disk  or  the  processor  is  on  fire. 

— q  reboots  quickly  and  ungracefully,  without  first  shutting  down  running  processes. 

Power  fail  and  crash  recovery.  Normally,  the  system  will  reboot  itself  at  power-up  or  after 
crashes.  When  it  reboots,  an  automatic  consistency  check  of  the  file  systems  is  done.  If  this 
check  is  successful,  the  system  resumes  multi-user  operations. 

The  boot  program  finds  the  corresponding  file  on  the  given  device,  loads  that  file  into  memory 
location  zero,  and  starts  the  program  at  the  entry  address  specified  in  the  program  header.  Nor¬ 
mal  line  editing  characters  can  be  used  in  specifying  the  pathname. 

For  tapes,  the  minor  device  number  gives  a  file  offset. 

FILES 

/vmunix  system  code 

/boot  system  bootstrap 

SEE  ALSO 

crash(8S),  fsck(8),  init(8),  rc(8),  shutdown(8),  halt(8),  newfs(8) 
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NAME 

recnews  —  receive  unprocessed  articles  via  mail 


SYNOPSIS 

/umr/lib/news/recnews  j  newsgroup  |  sender  ]  | 

DESCRIPTION 

Recnews  reads  a  letter  from  the  standard  input;  determines  the  article  title,  sender,  and  news- 
group;  and  gives  the  body  to  inews  with  the  right  arguments  for  insertion. 

If  newsgroup  is  omitted,  the  to  line  of  the  letter  is  used.  If  sender  is  omitted,  the  sender  is  deter¬ 
mined  from  the  from  line  of  the  letter.  The  title  is  determined  from  the  subject  line. 


SEE  ALSO 

inews(l),  uurec(8),  sendnews(8),  readnews(l),  checknews(l) 
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NAME 

re  nice  —  alter  priority  of  running  processes 
SYNOPSIS 

/etc/renice  [  — g  ]  [  — u  |  priority  who  ... 

DESCRIPTION 

Renice  can  be  used  to  alter  the  scheduling  priority  of  one  or  more  running  processes.  By  default, 
the  processes  to  be  affected  are  specified  by  their  process  id*s.  If  the  — g  option  is  specified,  the 
who  parameters  are  interpreted  as  process  groups  and  all  the  processes  in  the  specified  process 
groups  have  their  scheduling  priority  altered.  If  the  — u  option  is  indicated,  the  who  parameters 
are  interpreted  as  user  names  and  all  process  owned  by  the  user  are  affected. 

Users  other  than  the  super-user  may  only  alter  the  priority  of  processes  they  own,  and  can  only 
monotonically  increase  their  “nice  value*’  within  the  range  0  to  PRIO_MIN  (20).  (This  prevents 
overriding  administrative  fiats.)  The  super-user  may  alter  the  priority  of  any  process  and  set  the 
priority  to  any  value  in  the  range  PRIO_MAX  (*-20)  to  PRIO_MIN.  Useful  priorities  are:  19  (the 
affected  processes  will  run  only  when  nothing  else  in  the  system  wants  to),  0  (the  “base*’  schedul¬ 
ing  priority),  anything  negative  (to  make  things  go  very  fast). 

If  no  who  parameter  is  specified,  the  current  process  (alternatively,  process  group  or  user)  is  used. 

FILES 

/etc/passwd  to  map  user  names  to  user  id’s 

SEE  ALSO 

getpriority(2) 

BUGS 

If  you  make  the  priority  very  negative,  then  the  process  cannot  be  interrupted.  To  regain  control 
you  must  make  the  priority  greater  than  zero.  Non  super-users  can  not  increase  scheduling 
priorities  of  their  own  processes,  even  if  they  were  the  ones  that  decreased  the  priorities  in  the 
first  place. 
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NAME 

restore  —  incremental  file  system  restore 
SYNOPSIS 

/etc/restore  key  [  name  ...  ] 

DESCRIPTION 

Restort  restores  files  from  tapes  previously  created  via  the  dump (8)  command.  Restore's  actions 
are  controlled  by  the  key  argument.  The  key  is  a  string  of  characters  containing  at  most  one 
function  letter  and  possibly  one  or  more  function  modifiers.  Other  arguments  to  restore  are  file 
or  directory  names  specifying  the  files  that  are  to  be  restored.  Unless  the  h  key  is  specified  (see 
below),  the  appearance  of  a  directory  name  refers  to  the  files  and  (recursively)  subdirectories  of 
that  directory. 

FUNCTION  LETTERS 

The  function  portion  of  the  key  is  specified  by  one  of  the  following  letters: 

r  The  tape  is  read  and  loaded  into  the  current  directory.  This  should  not  be  done  lightly; 
the  r  key  should  only  be  used  to  restore  a  complete  dump  tape  onto  a  clear  file  system  or 
to  restore  an  incremental  dump  tape  after  a  full  level  zero  restore.  Thus: 
tutorial%  /etc/newfs  /dev/rxyOg  eagle 
tutorial%  /etc/mount  /dev/xyOg  /mnt 
tutorial%  cd  /mnt 
tutorial%  restore  r 

is  a  typical  sequence  to  restore  a  complete  dump.  Another  restore  can  be  done  to  get  an 
incremental  dump  in  on  top  of  this.  A  dump(8)  followed  by  a  neu;/?(8)  and  a  restore  can  be 
used  to  change  the  size  of  a  file  system. 

R  Restore  requests  a  particular  tape  of  a  multi  volume  set  on  which  to  restart  a  full  restore 

(see  the  r  key  above).  This  allows  restore  to  be  interrupted  and  then  restarted. 

X  Extract  the  named  files  from  the  tape.  If  the  named  file  matches  a  directory  whose  con¬ 

tents  had  been  written  onto  the  tape,  and  the  h  key  is  not  specified,  the  directory  is  recur¬ 
sively  extracted.  The  owner,  modification  time,  and  mode  are  restored  (if  possible).  If  no 
file  argument  is  given,  the  root  directory  is  extracted,  which  results  in  the  entire  content  of 
the  tape  being  extracted,  unless  the  h  key  has  been  specified. 

t  List  the  names  of  the  specified  files  if  they  occur  on  the  tape.  If  no  file  argument  is  given, 
the  root  directory  is  listed,  which  results  in  the  entire  content  of  the  tape  being  listed, 
unless  the  h  key  has  been  specified.  Note  that  the  t  key  replaces  the  function  of  the  old 
dump  dir  program. 

i  Restore  files  interactively  from  a  dump  tape.  After  reading  in  the  directory  information 
from  the  tape,  restore  provides  a  shell  like  interface  within  which  the  user  can  move  around 
the  directory  tree  selecting  files  to  be  extracted.  The  available  commands  that  this  ‘shell’ 
provides  are  given  below.  For  those  commands  that  require  an  argument,  the  default  is  the 
current  directory. 

U  [argj  List  the  current  or  specified  directory.  Entries  that  are  directories  are  appended 
with  a  7’.  Entries  that  have  been  marked  for  extraction  are  prepended  with  a 
If  the  verbose  key  is  set  the  inode  number  of  each  entry  is  also  listed, 

cd  arg  Change  the  current  working  directory  to  the  specified  argument, 
pwd  Print  the  full  pathname  of  the  current  working  directory. 

add  |arg|  Add  the  current  directory  or  specified  argument  to  the  list  of  files  to  be 
extracted.  If  a  directory  is  specified,  add  that  directory  and  all  its  to  the  extrac¬ 
tion  list  (unless  the  h  key  is  specified  on  the  command  line).  Files  that  are  on 
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the  extraction  list  are  prepended  with  a  when  they  are  listed  by  Is. 
delete  [arg| 

Delete  the  current  directory  or  specified  argument  from  the  list  of  files  to  be 
extracted.  If  a  directory  is  specified,  delete  that  directory  and  all  its  descen- 
dents  from  the  extraction  list  (unless  the  h  key  is  specified  on  the  command 
line).  The  most  expedient  way  to  extract  most  of  the  files  from  a  directory  is  to 
add  the  directory  to  the  extraction  list  and  then  delete  those  files  that  are  not 
needed. 

extract  Extract  from  the  dump  tape  all  the  files  that  are  on  the  extraction  list.  Reatore 
asks  which  volume  the  user  wishes  to  mount.  The  fastest  way  to  extract  a  few 
files  is  to  start  with  the  last  volume,  and  work  towards  the  first  volume. 

verboee  Toggle  the  sense  of  the  v  key.  When  the  verbose  key  is  set,  the  Is  command 
lists  the  inode  numbers  of  all  entries,  and  restore  also  displays  information  about 
each  file  as  it  is  extracted. 

help  List  a  summary  of  the  available  commands. 

quit  Restore  immediately  exits,  even  if  the  extraction  list  is  not  empty. 

FUNCTION  MODIFIERS 

The  function  modifiers  which  may  be  used  in  addition  to  the  function  letters  are  as  follows.  A 

few  of  these  modifiers  —  namely  b,  f,  and  ■—  take  an  argument  from  the  command  line.  If  you 

use  more  than  one  of  b,  f,  and  s,  nest  your  arguments  as  you  do  your  modifiers;  if  you  use  b  first 

on  the  command  line,  place  its  argument  first  on  the  command  line,  and  so  on. 

b  Specifies  the  blocking  factor  for  the  restore.  The  blocking  factor  is  taken  from  the  next 
argument  on  the  command  line.  This  corresponds  to  the  b  key  in  dump(8). 

d  Turns  on  debugging  output. 

V  This  is  the  verbose  option.  It  means  display  the  name  of  each  file  it  treats  preceded  by  its 
file  type.  Restore  normally  works  silently. 

f  Use  the  next  argument  to  restore  as  the  name  of  the  archive  instead  of  /dev/rmt?.  If  the 
name  of  the  file  is  restore  reads  from  standard  input.  Thus,  rf«mp(8)  and  restore  can  be 
used  in  a  pipeline  to  dump  and  restore  a  file  system  with  the  command 
tutorial^  dump  Of  —  /uar  |  (cd  /mnt;  restore  xf  — ) 

If  the  name  of  the  file  is  ‘machinerdevice’  the  restore  is  done  from  the  specified  machine 
through  the  internet  using  rml(8C). 

s  The  next  argument  to  restore  is  the  number  of  files  to  skip  in  the  case  where  there  are  mul¬ 
tiple  dump  files  on  the  dump  tape.  For  example,  a  command  like 
tutorial%  restore  xfs  /dev/nrarO  5 
would  position  you  at  the  sixth  file  on  the  tape. 

y  Do  not  ask  whether  to  abort  the  restore  in  the  event  of  tape  errors.  Restore  always  tries  to 
skip  over  the  bad  tape  block(s)  and  continue  as  best  it  can. 

m  Extract  by  inode  numbers  rather  than  by  file  name.  This  is  useful  if  only  a  few  files  are 
being  extracted,  and  one  wants  to  avoid  regenerating  the  complete  pathname  to  the  file. 

h  Extract  the  actual  directory,  rather  than  the  files  that  it  references.  This  prevents 
hierarchical  restoration  of  complete  subtrees  from  the  tape. 

c  Convert  the  contents  of  the  dump  tape  to  the  new  file  system  format. 

DIAGNOSTICS 

Complaints  about  bad  key  characters. 
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Complaints  if  it  gets  a  read  error.  If  y  has  been  specified,  or  the  user  responds  restore  will 
attempt  to  continue  the  restore. 

If  the  dump  extends  over  more  than  one  tape,  restore  asks  the  user  to  change  tapes.  If  the  x  or  1 
key  has  been  specified,  restore  also  asks  which  volume  the  user  wishes  to  mount.  The  fastest 
way  to  extract  a  few  files  is  to  start  with  the  last  volume,  and  work  towards  the  first  volume. 

There  are  numerous  consistency  checks  that  can  be  listed  by  restore.  Most  checks  are  self- 
explanatory  or  can  ‘never  happen*.  Common  errors  are  given  below. 

Converting  to  new  file  system  format. 

A  dump  tape  created  from  the  old  file  system  has  been  loaded.  It  is  automatically  con¬ 
verted  to  the  new  file  system  format. 

<filename>:  not  found  on  tape 

The  specified  file  name  was  listed  in  the  tape  directory,  but  was  not  found  on  the  tape. 
This  is  caused  by  tape  read  errors  while  looking  for  the  file,  and  from  using  a  dump  tape 
created  on  an  active  file  system. 

expected  next  file  <inumber>,  got  <inumber> 

A  file  that  was  not  listed  in  the  directory  showed  up.  This  can  occur  when  using  a  dump 
tape  created  on  an  active  file  system. 

Incremental  tape  too  low 

When  doing  incremental  restore,  a  tape  that  was  written  before  the  previous  incremental 
tape,  or  that  has  too  low  an  incremental  level  has  been  loaded. 

Incremental  tape  too  high 

When  doing  incremental  restore,  a  tape  that  does  not  begin  its  coverage  where  the  previous 
incremental  tape  left  off,  or  that  has  too  high  an  incremental  level  has  been  loaded. 

Tape  read  error  while  restoring  <filename> 

Tape  read  error  while  skipping  over  inode  <inumber> 

Tape  read  error  while  trying  to  resynchronize 

A  tape  read  error  has  occurred.  If  a  file  name  is  specified,  then  its  contents  are  probably 
partially  wrong.  If  an  inode  is  being  skipped  or  the  tape  is  trying  to  resynchronize,  then  no 
extracted  files  have  been  corrupted,  though  files  may  not  be  found  on  the  tape. 

resync  restore,  skipped  <num>  blocks 

After  a  tape  read  error,  restore  may  have  to  resynchronize  itself.  This  message  lists  the 
number  of  blocks  that  were  skipped  over. 

FILES 

/dev/rmt?  the  default  tape  drive 
/tmp/rstdir*  file  containing  directories  on  the  tape. 

/tmp/rstmode^  owner,  mode,  and  time  stamps  for  directories. 

./restoresymtab  information  passed  between  incremental  restores. 

SEE  ALSO 

dump(8),  newfs(8),  mount(8),  mkfs(8),  rmt(8C) 

BUGS 

Restore  can  get  confused  when  doing  incremental  restores  from  dump  tapes  that  were  made  on 
active  file  systems, 

A  level  zero  dump  must  be  done  after  a  full  restore.  Because  restore  runs  in  user  mode,  it  has  no 
control  over  inode  allocation;  this  means  that  restore  re-positions  the  files,  although  it  does 
change  their  contents.  Thus,  a  full  dump  must  be  done. to  get  a  new  set  of  directories  reflecting 
the  new  file  positions,  so  that  later  incremental  dumps  will  be  correct. 
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NAME 

rexecd  —  remote  execution  server 
SYNOPSIS 

/u8r/etc/in«rexecd  host. port 
DESCRIPTION 

Rexecd  is  the  server  for  the  re2rec(3N)  routine.  The  server  provides  remote  execution  facilities 
with  authentication  based  on  user  names  and  encrypted  passwords.  It  is  invoked  automatically 
as  needed  by  meW(8C),  and  then  executes  the  following  protocol: 

1)  The  server  reads  characters  from  the  socket  up  to  a  null  (*\0^)  byte.  The  resultant  string 
is  interpreted  as  an  ASCII  number,  base  10. 

2)  If  the  number  received  in  step  1  is  non-zero,  it  is  interpreted  as  the  port  number  of  a 
secondary  stream  to  be  used  for  the  stderr.  A  second  connection  is  then  created  to  the 
specified  port  on  the  client's  machine. 

3)  A  null  terminated  user  name  of  at  most  16  characters  is  retrieved  on  the  initial  socket. 

4)  A  null  terminated,  encrypted,  password  of  at  most  16  characters  is  retrieved  on  the  ini¬ 
tial  socket. 

5)  A  null  terminated  command  to  be  passed  to  a  shell  is  retrieved  on  the  initial  socket.  The 
length  of  the  command  is  limited  by  the  upper  bound  on  the  size  of  the  system’s  argu¬ 
ment  list. 

6)  Rexecd  then  validates  the  user  as  is  done  at  login  time  and,  if  the  authentication  was 
successful,  changes  to  the  user’s  home  directory,  and  establishes  the  user  and  group  pro¬ 
tections  of  the  user.  If  any  of  these  steps  fail  the  connection  is  aborted  with  a  diagnostic 
message  returned. 

7)  A  null  byte  is  returned  on  the  connection  associated  with  the  stderr  and  the  command 
line  is  passed  to  the  normal  login  shell  of  the  user.  The  shell  inherits  the  network  con¬ 
nections  established  by  rexecd, 

DIAGNOSTICS 

All  diagnostic  messages  are  returned  on  the  connection  associated  with  the  stderr,  after  which 
any  network  connections  are  closed.  An  error  is  indicated  by  a  leading  byte  with  a  value  of  1  (0 
is  returned  in  step  7  above  upon  successful  completion  of  all  the  steps  prior  to  the  command  exe¬ 
cution). 

^‘uBername  too  long’* 

The  name  is  longer  than  16  characters. 

^^pasBword  too  long** 

The  password  is  longer  than  16  characters. 

“command  too  long  ** 

The  command  line  passed  exceeds  the  size  of  the  argument  list  (as  configured  into  the  system). 

“Login  incorrect*** 

No  password  file  entry  for  the  user  name  existed. 

“Password  incorrect*** 

The  wrong  password  was  supplied. 

“No  remote  directory*** 

The  chdir  command  to  the  home  directory  failed. 

“Try  again.** 

A  fork  by  the  server  failed. 
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‘‘/bln/sh: ..." 

The  user’s  login  shell  could  not  be  started. 


BUGS 

Indicating  “Login  incorrect”  as  opposed  to  “Password  incorrect”  is  a  security  breach  which 
allows  people  to  probe  a  system  for  users  with  null  passwords. 

A  facility  to  allow  all  data  exchanges  to  be  encrypted  should  be  present. 

SEE  ALSO 

inetd(8C) 
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NAME 

riogind  —  remote  login  server 
SYNOPSIS 

/etc/in.rloglnd  host.port 
DESCRIPTION 

Riogind  is  the  server  for  the  rlogin(lC)  program.  The  server  provides  a  remote  login  facility 
with  authentication  based  on  privileged  port  numbers. 

Riogind  is  invoked  by  tne<rf(8C)  when  a  remote  login  connection  is  established,  and  executes  the 
following  protocol: 

1)  The  server  checks  the  client’s  source  port.  If  the  port  is  not  in  the  range  0-1023,  the 
server  aborts  the  connection.  The  client’s  address  and  port  number  are  passed  as  argu¬ 
ments  to  riogind  by  inetd  in  the  form  “host.port”  with  host  in  hex  and  port  in  decimal. 

2)  The  server  checks  the  client’s  source  address.  If  the  address  is  associated  with  a  host  for 
which  no  corresponding  entry  exists  in  the  host  name  data  base  (see  Aoe<e(5)),  the  server 
aborts  the  connection. 

Once  the  source  port  and  address  have  been  checked,  riogind  allocates  a  pseudo  terminal  (see 
ptj/(4)),  and  manipulates  file  descriptors  so  that  the  slave  half  of  the  pseudo  terminal  becomes  the 
etdtn  ,  stdout  ,  and  stderr  for  a  login  process.  The  login  process  is  an  instance  of  the  login(l) 
program,  invoked  with  the  — r  option.  The  login  process  then  proceeds  with  the  authentication 
process  as  described  in  rshd(8C),  but  if  automatic  authentication  fails,  it  reprompts  the  user  to 
login  as  one  finds  on  a  standard  terminal  line. 

The  parent  of  the  login  process  manipulates  the  master  side  of  the  pseudo  terminal,  operating  as 
an  intermediary  between  the  login  process  and  the  client  instance  of  the  rlogin  program.  In  nor¬ 
mal  operation,  the  packet  protocol  described  in  p<j/(4)  is  invoked  to  provide  "S/*Q  type  facilities 
and  propagate  interrupt  signals  to  the  remote  programs.  The  login  process  propagates  the  client 
terminal’s  baud  rate  and  terminal  type,  as  found  in  the  environment  variable,  “TERM”;  see 
ent;tron(5). 

DIAGNOSTICS 

All  diagnostic  messages  are  returned  on  the  connection  associated  with  the  stderr,  after  which 
any  network  connections  are  closed.  An  error  is  indicated  by  a  leading  byte  with  a  value  of  1. 

“Hostname  for  your  address  unknown.'* 

No  entry  in  the  host  name  database  existed  for  the  client’s  machine. 

“Try  again.” 

A.  fork  by  the  server  failed, 

“/bin/sh!  ...” 

The  user’s  login  shell  could  not  be  started. 

BUGS 

The  authentication  procedure  used  here  assumes  the  integrity  of  each  client  machine  and  the 
connecting  medium.  This  is  insecure,  but  is  useful  in  an  “open”  environment. 

A  facility  to  allow  all  data  exchanges  to  be  encrypted  should  be  present. 

SEE  ALSO 

inetd{8C) 
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NAME 

rmail  -  handle  remote  mail  received  via  uucp 


SYNOPSIS 

rmail  user  ... 


DESCRIPTION 

Email  interprets  incoming  mail  received  via  uucp  (1C),  collapsing  “From”  lines  in  the  form  gen¬ 
erated  by  binmail(l)  into  a  single  line  of  the  form  “return-pathlsender”,  and  passing  the  pro¬ 
cessed  mail  on  to  sen(/mot7(8). 

RmaU  is  explicitly  designed  for  use  with  uucp  and  sendmail. 


SEE  ALSO 

binmail(l),  uucp(lC),  sendmail(8) 

BUGS 

Email  should  not  reside  in  /bin. 
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NAME 

rmt  —  remote  magtape  protocol  module 

SYNOPSIS 

/etc /rmt 

DESCRIPTION 

Rmt  is  a  program  used  by  the  remote  dump  and  restor  programs  in  manipulating  a  magnetic 
tape  drive  through  an  interprocess  communication  connection.  Rmt  is  normally  started  up  with 
an  rea:ec(3N)  or  rcmrf(3N)  call. 

The  rmt  program  accepts  requests  specific  to  the  manipulation  of  magnetic  tapes,  performs  the 
commands,  then  responds  with  a  status  indication.  All  responses  are  in  ASCII  and  in  one  of  two 
forms.  Successful  commands  have  responses  of 

Anumber\n 

where  number  is  an  ASCII  representation  of  a  decimal  number.  Unsuccessful  commands  are 
responded  to  with 

Eerror’numb€r\ii€rror‘me93age\nj 

where  error-number  is  one  of  the  possible  error  numbers  described  in  intro{2)  and  error-message 
is  the  corresponding  error  string  as  printed  from  a  call  to  perror(3).  The  protocol  is  comprised  of 
the  following  commands  (a  space  is  present  between  each  token). 

O  device  mode 

Open  the  specified  device  using  the  indicated  mode.  Device  is  a  full  pathname 
and  mode  is  an  ASCII  representation  of  a  decimal  number  suitable  for  passing  to 
open{2).  If  a  device  had  already  been  opened,  it  is  closed  before  a  new  open  is 
performed. 

C  device  Close  the  currently  open  device.  The  device  specified  is  ignored. 

L  whence  offset 

Perform  an  /^ee^(2)  operation  using  the  specified  parameters.  The  response 
value  is  that  returned  from  the  Iseek  call. 

W  count  Write  data  onto  the  open  device.  Rmt  reads  count  bytes  from  the  connection, 

aborting  if  a  premature  end-of-file  is  encountered.  The  response  value  is  that 
returned  from  the  write{2)  call. 

R  count  Read  count  bytes  of  data  from  the  open  device.  Rmt  performs  the  requested 

read{2)  and  responds  with  Acount-reai\n  if  the  read  was  successful;  otherwise 
an  error  in  the  standard  format  is  returned.  If  the  read  was  successful,  the  data 
read  is  then  sent. 

I  operation  count 

Perform  a  MTIOCOP  ioctl{2)  command  using  the  specified  parameters.  The 
parameters  are  interpreted  as  the  ASCII  representations  of  the  decimal  values  to 
place  in  the  mt^op  and  miscount  fields  of  the  structure  used  in  the  ioctl  call. 
The  return  value  is  the  count  parameter  when  the  operation  is  successful. 

S  Return  the  status  of  the  open  device,  as  obtained  with  a  MTIOCGET  ioctt  call. 

If  the  operation  was  successful,  an  ‘‘ack”  is  sent  with  the  size  of  the  status 
buffer,  then  the  status  buffer  is  sent  (in  binary). 

Any  other  command  causes  rmt  to  exit. 

DIAGNOSTICS 

All  responses  are  of  the  form  described  above. 
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SEE  ALSO 

rcmd(3N),  rexec(3N),  mtio(4),  dump(8),  restorc(8) 

BUGS 

People  tempted  to  use  this  for  a  remote  file  access  protocol  are  discouraged. 
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NAME 

route  —  manually  manipulate  the  routing  tables 
SYNOPSIS 

/uBr/etc/route  [  -“f  1  [  command  atgs  j 
DESCRIPTION 

Route  is  a  program  used  to  manually  manipulate  the  network  routing  tables.  It  normally  is  not 
needed,  as  the  system  routing  table  management  daemon,  ro«Ied(8C),  should  tend  to  this  task. 

Route  accepts  three  commands:  add,  to  add  a  route;  delete,  to  delete  a  route;  and  change,  to 
modify  an  existing  route. 

All  commands  have  the  following  syntax: 

/usr/etc/route  command  destination  gateway  [  metric  | 

where  destination  is  a  host  or  network  for  which  the  route  is  “to”,  gateway  is  the  gateway  to 
which  packets  should  be  addressed,  and  metric  is  an  optional  count  indicating  the  number  of 
hops  to  the  destination.  If  no  metric  is  specified,  route  assumes  a  value  of  0.  Routes  to  a  partic¬ 
ular  host  are  distinguished  from  those  to  a  network  by  interpreting  the  Internet  address  associ¬ 
ated  with  destination.  If  the  destination  has  a  “local  address  part”  of  INADDR^ANY,  then  the 
route  is  assumed  to  be  to  a  network;  otherwise,  it  is  presumed  to  be  a  route  to  a  host.  If  the 
route  is  to  a  destination  connected  via  a  gateway,  the  metric  should  be  greater  than  0.  All  sym¬ 
bolic  names  specified  for  a  destination  or  gateway  are  looked  up  first  in  the  host  name  database, 
If  this  lookup  fails,  the  name  is  then  looked  for  in  the  network  name  database,  net- 

works[b). 

Route  uses  a  raw  socket  and  the  SIOCADDRT  and  SIOCDELRT  iocWs  to  do  its  work.  As  such, 
only  the  super-user  may  modify  the  routing  tables. 

If  the  —f  option  is  specified,  route  will  “flush”  the  routing  tables  of  all  gateway  entries.  If  this  is 
used  in  conjunction  with  one  of  the  commands  described  above,  the  tables  are  flushed  prior  to 
the  command’s  application, 

DIAGNOSTICS 

**add  %B!  gateway  %b  flage 

The  specified  route  is  being  added  to  the  tables.  The  values  printed  are  from  the  routing  table 
entry  supplied  in  the  ioctl  call. 

“delete  %b:  gateway  %b  flags 

As  above,  but  when  deleting  an  entry. 

%B  done” 

When  the  — f  flag  is  specified,  each  routing  table  entry  deleted  is  indicated  with  a  message  of  this 
form. 

“not  In  table” 

A  delete  operation  was  attempted  for  an  entry  which  wasn’t  present  in  the  tables. 

“routing  table  overflow” 

An  add  operation  was  attempted,  but  the  system  was  low  on  resources  and  was  unable  to  allo¬ 
cate  memory  to  create  the  new  entry. 

SEE  ALSO 

routing(4N),  routed(8C) 

BUGS 

The  change  operation  is  not  implemented,  one  should  add  the  new  route,  then  delete  the  old  one. 
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NAME 

routed  —  network  routing  daemon 
SYNOPSIS 

/etc/ln.routed  [  *-•  ]  (  --q  i  [  “t  ]  [  logfiie  ] 

DESCRIPTION 

Routed  is  invoked  at  boot  time  to  manage  the  network  routing  tables.  The  routing  daemon  uses 
a  variant  of  the  Xerox  NS  Routing  Information  Protocol  in  maintaining  up  to  date  kernel  routing 
table  entries. 

In  normal  operation  routed  listens  on  udp{4P)  socket  520  (decimal)  for  routing  information  pack¬ 
ets.  If  the  host  is  an  internetwork  router,  it  periodically  supplies  copies  of  its  routing  tables  to 
any  directly  connected  hosts  and  networks. 

When  routed  is  started,  it  uses  the  SIOCGIFCONF  ioctl  to  find  those  directly  connected  inter¬ 
faces  configured  into  the  system  and  marked  “up’*  (the  software  loopback  interface  is  ignored). 
If  multiple  interfaces  are  present,  it  is  assumed  the  host  will  forward  packets  between  networks. 
Routed  then  transmits  a  request  packet  on  each  interface  (using  a  broadcast  packet  if  the  inter¬ 
face  supports  it)  and  enters  a  loop,  listening  for  request  and  response  packets  from  other  hosts. 

When  a  request  packet  is  received,  routed  formulates  a  reply  based  on  the  information  main¬ 
tained  in  its  internal  tables.  The  response  packet  generated  contains  a  list  of  known  routes,  each 
marked  with  a  “hop  count’*  metric  (a  count  of  16,  or  greater,  is  considered  “infinite”).  The 
metric  associated  with  each  route  returned  provides  a  metric  relative  to  the  sender. 

Request  packets  received  by  routed  are  used  to  update  the  routing  tables  if  one  of  the  following 
conditions  is  satisfied: 

(1)  No  routing  table  entry  exists  for  the  destination  network  or  host,  and  the  metric  indi¬ 
cates  the  destination  is  “reachable**  (that  is,  the  hop  count  is  not  infinite). 

(2)  The  source  host  of  the  packet  is  the  same  as  the  router  in  the  existing  routing  table 
entry.  That  is,  updated  information  is  being  received  from  the  very  internetwork  router 
through  which  packets  for  the  destination  are  being  routed. 

(3)  The  existing  entry  in  the  routing  table  has  not  been  updated  for  some  time  (defined  to  be 
90  seconds)  and  the  route  is  at  least  as  cost  effective  as  the  current  route. 

(4)  The  new  route  describes  a  shorter  route  to  the  destination  than  the  one  currently  stored 
in  the  routing  tables;  the  metric  of  the  new  route  is  compared  against  the  one  stored  in 
the  table  to  decide  this. 

When  an  update  is  applied,  routed  records  the  change  in  its  interna!  tables  and  generates  a 
response  packet  to  all  directly  connected  hosts  and  networks.  Routed  waits  a  short  period  of 
time  (no  more  than  30  seconds)  before  modifying  the  kernel’s  routing  tables  to  allow  possible 
unstable  situations  to  settle. 

In  addition  to  processing  incoming  packets,  routed  also  periodically  checks  the  routing  table 
entries.  If  an  entry  has  not  been  updated  for  3  minutes,  the  entry’s  metric  is  set  to  infinity  and 
marked  for  deletion.  Deletions  are  delayed  an  additional  60  seconds  to  insure  the  invalidation  is 
propagated  throughout  the  internet. 

Hosts  acting  as  internetwork  routers  gratuitously  supply  their  routing  tables  every  30  seconds  to 
all  directly  connected  hosts  and  networks. 

Supplying  the  — •  option  forces  routed  to  supply  routing  information  whether  it  is  acting  as  an 
internetwork  router  or  not.  The  — q  option  is  the  opposite  of  the  — s  option.  If  the  — t  option  is 
specified,  all  packets  sent  or  received  are  printed  on  the  standard  output.  In  addition,  routed  will 
not  divorce  itself  from  the  controlling  terminal  so  that  interrupts  from  the  keyboard  will  kill  the 
process.  Any  other  argument  supplied  is  interpreted  as  the  name  of  file  in  which  routed's  actions 
should  be  logged.  This  log  contains  information  about  any  changes  to  the  routing  tables  and  a 
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history  of  recent  messages  sent  and  received  which  are  related  to  the  changed  route. 

In  addition  to  the  facilities  described  above,  routed  supports  the  notion  of  “distant”  passive  and 
active  gateways.  When  routed  is  started  up,  it  reads  the  file  /etc/gateways  to  find  gateways 
which  may  not  be  identified  using  the  SIOGIFCONF  ioctL  Gateways  specified  in  this  manner 
should  be  marked  passive  if  they  are  not  expected  to  exchange  routing  information,  while  gate¬ 
ways  marked  active  should  be  willing  to  exchange  routing  information  (that  is,  they  should  have 
a  routed  process  running  on  the  machine).  Passive  gateways  are  maintained  in  the  routing  tables 
forever  and  information  regarding  their  existence  is  included  in  any  routing  information  transmit¬ 
ted.  Active  gateways  are  treated  equally  to  network  interfaces.  Routing  information  is  distri¬ 
buted  to  the  gateway  and  if  no  routing  information  is  received  for  a  period  of  the  time,  the  asso¬ 
ciated  route  is  deleted. 

The  /etc/ gateways  is  comprised  of  a  series  of  lines,  each  in  the  following  format: 

<  net  j  host  >  namel  gateway  nameS  metric  value  <  passive  [  active  > 

The  net  or  host  keyword  indicates  if  the  route  is  to  a  network  or  specific  host. 

Namel  is  the  name  of  the  destination  network  or  host.  This  may  be  a  symbolic  name  located  in 
/etc/ networks  or  /etc/ hosts ^  or  an  Internet  address  specified  in  “dot”  notation;  see  me^(3N). 

Name2  is  the  name  or  address  of  the  gateway  to  which  messages  should  be  forwarded. 

Value  is  a  metric  indicating  the  hop  count  to  the  destination  host  or  network. 

The  keyword  passive  or  active  indicates  if  the  gateway  should  be  treated  as  passive  or  active 
(as  described  above), 

FILES 

/etc/gateways  for  distant  gateways 
SEE  ALSO 

Internet  Transport  Protocols,  XSIS  D28112,  Xerox  System  Integration  Standard.  (Sun  800-1065- 

01) 

udp(4P) 

BUGS 

The  kernePs  routing  tables  may  not  correspond  to  those  of  routed  for  short  periods  of  time  while 
processes  utilizing  existing  routes  exit;  the  only  remedy  for  this  is  to  place  the  routing  process  in 
the  kernel. 

Routed  should  listen  to  intelligent  interfaces,  such  as  an  IMP,  and  to  error  protocols,  such  as 
ICMP,  to  gather  more  information. 
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NAME 

rpcinfo  —  report  RPC  information 

SYNOPSIS 

rpcinfo  —p  I  host  ] 

rpcinfo  — u  host  program-number  version-number 
rpcinfo  — t  host  program-number  version-number 

DESCRIPTION 

Rpcinfo  makes  an  RPC  call  to  an  RPC  server  and  reports  what  it  finds. 

OPTIONS 

— p  Probe  the  portmapper  on  host^  and  print  a  list  of  all  registered  RPC  programs.  If  hoot  is 

not  specified,  it  defaults  to  the  value  returned  by  ho8tname{\), 

— u  Make  an  RPC  call  to  procedure  0  of  program-number  using  UDP,  and  report  whether  a 

response  was  received. 

— t  Make  an  RPC  call  to  procedure  0  of  program-number  using  TCP,  and  report  whether  a 

response  was  received. 

SEE  ALSO 

RPC  Reference  Manual,  portmap(8) 
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NAME 

rshd  —  remote  shell  server 
SYNOPSIS 

/etc/in*rBhd  host. port 
DESCRIPTION 

Rshd  is  the  server  for  the  rcmd(3N)  routine  and,  consequently,  for  the  r^A(lC)  program.  The 
server  provides  remote  execution  facilities  with  authentication  based  on  privileged  port  numbers, 

Rshd  is  invoked  by  tneW(8C)  each  time  a  shell  service  is  requested,  and  executes  the  following 
protocol: 

1)  The  server  checks  the  client’s  source  port.  If  the  port  is  not  in  the  range  0-1023,  the 
server  aborts  the  connection.  The  clients  host  address  (in  hex)  and  port  number  (in 
decimal)  are  the  argument  passed  to  rshd, 

2)  The  server  reads  characters  from  the  socket  up  to  a  null  (‘\0’)  byte.  The  resultant  string 
is  interpreted  as  an  ASCII  number,  base  10. 

3)  If  the  number  received  in  step  1  is  non-zero,  it  is  interpreted  as  the  port  number  of  a 
secondary  stream  to  be  used  for  the  stderr.  A  second  connection  is  then  created  to  the 
specified  port  on  the  client’s  machine.  The  source  port  of  this  second  connection  is  also 
in  the  range  0-1023. 

4)  The  server  checks  the  client’s  source  address.  If  the  address  is  associated  with  a  host  for 
which  no  corresponding  entry  exists  in  the  host  name  data  base  (see  Ao^fs(5)),  the  server 
aborts  the  connection. 

6)  A  null  terminated  user  name  of  at  most  16  characters  is  retrieved  on  the  initial  socket. 
This  user  name  is  interpreted  as  a  user  identity  to  use  on  the  server’s  machine. 

6)  A  null  terminated  user  name  of  at  most  16  characters  is  retrieved  on  the  initial  socket. 
This  user  name  is  interpreted  as  the  user  identity  on  the  client’s  machine. 

7)  A  null  terminated  command  to  be  passed  to  a  shell  is  retrieved  on  the  initial  socket.  The 
length  of  the  command  is  limited  by  the  upper  bound  on  the  size  of  the  system’s  argu¬ 
ment  list. 

8)  Rshd  then  validates  the  user  according  to  the  following  steps.  The  remote  user  name  is 
looked  up  in  the  password  file  and  a  chdir  is  performed  to  the  user’s  home  directory.  If 
the  lookup  or  fails,  the  connection  is  terminated.  If  the  chdir  fails,  it  does  a  chdir  to  / 
(root).  If  the  user  is  not  the  super-user,  (user  id  0),  the  file  / etc/hosts, equiv  is  consulted 
for  a  list  of  hosts  considered  “equivalent”.  If  the  client’s  host  name  is  present  in  this  file, 
the  authentication  is  considered  successful.  If  the  lookup  fails,  or  the  user  is  the  super- 
user,  then  the  file  ,rhoste  in  the  home  directory  of  the  remote  user  is  checked  for  the 
machine  name  and  identity  of  the  user  on  the  client’s  machine.  If  this  lookup  fails,  the 
connection  is  terminated. 

9)  A  null  byte  is  returned  on  the  connection  associated  with  the  stderr  and  the  command 
line  is  passed  to  the  normal  login  shell  of  the  user.  The  shell  inherits  the  network  con¬ 
nections  established  by  rshd, 

DIAGNOSTICS 

All  diagnostic  messages  are  returned  on  the  connection  associated  with  the  stderr,  after  which 
any  network  connections  are  closed.  An  error  is  indicated  by  a  leading  byte  with  a  value  of  1  (0 
is  returned  in  step  9  above  upon  successful  completion  of  all  the  steps  prior  to  the  command  exe¬ 
cution). 

“locuser  too  long** 

The  name  of  the  user  on  the  client’s  machine  is  longer  than  16  characters. 
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**rcmu8er  too  long** 

The  name  of  the  user  on  the  remote  machine  is  longer  than  16  characters. 

**command  too  long  ” 

The  command  line  passed  exceeds  the  size  of  the  argument  list  (as  configured  into  the  system). 

* 'Hostname  for  your  address  unknown.** 

No  entry  in  the  host  name  database  existed  for  the  client’s  machine, 

"Login  Incorrect.** 

No  password  file  entry  for  the  user  name  existed. 

"Permission  denied.** 

The  authentication  procedure  described  above  failed. 

"Can*t  make  pipe.** 

The  pipe  needed  for  the  stderr,  wasn’t  created. 

"Try  again.** 

A  fork  by  the  server  failed. 

"/bln/sh:  ...*’ 

The  user’s  login  shell  could  not  be  started. 

SEE  ALSO 

rsh(lC),  rcmd(3N) 

BUGS 

The  authentication  procedure  used  here  assumes  the  integrity  of  each  client  machine  and  the 
connecting  medium.  This  is  insecure,  but  is  useful  in  an  “open”  environment. 

A  facility  to  allow  all  data  exchanges  to  be  encrypted  should  be  present. 
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NAME 

rstatd  “  kernel  statistics  server 

SYNOPSIS 

/  U8P /etc /rpc«r  staid 

DESCRIPTION 

Rsiald  is  a  server  which  returns  performance  statistics  obtained  from  the  kernel.  These  statistics 
are  graphically  displayed  by  per/me^er(l).  The  rstatd  daemon  is  normally  invoked  by  fne<rf(8C). 

SEE  ALSO 

perfmeter(l),  services(5),  inetd(8) 
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NAME 

rwalld  —  network  rwall  server 


SYNOPSIS 

/  usr/etc/ rpc.r  walld 


DESCRIPTION  ...  o  V  n- 

Rwalld  is  a  server  that  handles  ru>a/l(l)  and  sAutiou;n(l)  requests.  It  is  implemented  by  calling 
to  all  the  appropriate  network  machines.  The  rwalld  daemon  is  normally  invoked  by 

irtetd(8C). 


SEE  ALSO 

rwall(l),  wall(l),  services(5),  inetd(8),  shutdown(8) 
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NAME 

rwhod  —  system  status  server 

SYNOPSIS 

/etc/rwhod 

DESCRIPTION 

Rwhod  is  the  server  which  maintains  the  database  used  by  the  r«;A(?(lC)  and  r«p^ime(lC)  pro¬ 
grams.  Its  operation  is  predicated  on  the  ability  to  broadcast  messages  on  a  network. 

Rwhod  operates  as  both  a  producer  and  consumer  of  status  information.  As  a  producer  of  infor¬ 
mation  it  periodically  queries  the  state  of  the  system  and  constructs  status  messages  which  are 
broadcast  on  a  network.  As  a  consumer  of  information,  it  listens  for  other  rwhod  servers’  status 
messages,  validating  them,  then  recording  them  in  a  collection  of  files  located  in  the  directory 
fusrf  spool/ rwho. 

The  rwho  server  transmits  and  receives  messages  at  the  port  indicated  in  the  “rwho”  service 
specification,  see  8€rvice8{sy  The  messages  sent  and  received,  are  of  the  form: 

struct  outmp  { 

char  outJine[8];  /♦  tty  name  ♦/ 

char  out_name[8];  /♦  user  id  */ 

long  outjime;  /♦  time  on  ♦/ 

}: 

struct  whod  { 

char  wd^vers; 

char  wd_type; 

char  wd_fill[2l; 

int  wd^sendtime; 

int  wd_recvtime; 

char  wd_hostname[32]; 
int  wdJoadav[3|; 

int  wd_boottime; 

struct  whoent  { 

struct  outmp  we_utmp; 

int  weJdle; 

}  wd_we[l024  /  sizeof  (struct  whoent)]; 

}: 

All  fields  are  converted  to  network  byte  order  prior  to  transmission.  The  load  averages  are  as 
calculated  by  the  ty(l)  program,  and  represent  load  averages  over  the  5,  10,  and  15  minute  inter¬ 
vals  prior  to  a  server’s  transmission.  The  host  name  included  is  that  returned  by  the  gethost- 
name{2)  system  call.  The  array  at  the  end  of  the  message  contains  information  about  the  users 
logged  in  to  the  sending  machine.  This  information  includes  the  contents  of  the  ufmp(5)  entry 
for  each  non-idle  terminal  line  and  a  value  indicating  the  time  since  a  character  was  last  received 
on  the  terminal  line. 

Messages  received  by  the  rwko  server  are  discarded  unless  they  originated  at  a  rwho  server’s 
port.  In  addition,  if  the  host’s  name,  as  specified  in  the  message,  contains  any  unprintable  ASCII 
characters,  the  message  is  discarded.  Valid  messages  received  by  rwhod  are  placed  in  files  named 
whod. hostname  in  the  directory  fusrf spool/ rwho.  These  files  contain  ojily  the  most  recent  mes¬ 
sage,  in  the  format  described  above. 

Status  messages  are  generated  approximately  once  every  60  seconds.  Rwhod  performs  an  n/iV^(3) 
on  /vmunix  every  10  minutes  to  guard  against  the  possibility  that  this  file  is  not  the  system 
image  currently  operating. 
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SEE  ALSO 

rwho(lC),  ruptime(lC) 

BUGS 

Should  relay  status  information  between  networks.  People  often  interpret  the  server  dying  as  a 
machine  going  down. 


582 


Last  change;  28  October  1983 


Sun  Release  2.0 


SA(8) 


MAINTENANCE  COMMANDS 


SA{8) 


NAME 

sa,  accton  —  system  accounting 
SYNOPSIS 

/usr/etc/Ba  [  -abcdDflJkKlnrstuv  [  |  file  ] 

/usr /ete/accton  |  file  j 
DESCRIPTION 

With  an  argument  naming  an  existing  file,  accton  causes  system  accounting  information  for  every 
process  executed  to  be  placed  at  the  end  of  the  file.  If  no  argument  is  given,  accounting  is  turned 
off. 

Sa  reports  on,  cleans  up,  and  generally  maintains  accounting  files. 

Sa  is  able  to  condense  the  information  in  /usr/adm/acct  into  a  summary  file  fuar/adm/oavacct 
which  contains  a  count  of  the  number  of  times  each  command  was  called  and  the  time  resources 
consumed.  This  condensation  is  desirable  because  on  a  large  system  /usrf  adm/acct  can  grow  by 
500K  bytes  per  day.  The  summary  file  is  normally  read  before  the  accounting  file,  so  the  reports 
include  all  available  information. 

If  a  file  name  is  given  as  the  last  argument,  that  file  will  be  treated  as  the  accounting  file; 
/usr/adm/acct  is  the  default. 

Output  fields  are  labelled:  ‘cpu’  for  the  sum  of  user+system  time  (in  minutes),  ‘re’  for  real  time 
(also  in  minutes),  ‘k’  for  cpu-time  averaged  core  usage  (in  Ik  units),  ‘avio’  for  average  number  of 
I/O  operations  per  execution.  With  options  fields  labelled  ‘tio’  for  total  I/O  operations,  ‘k*sec’ 
for  cpu  storage  integral  (kilo-core  seconds),  *u’  and  V  for  user  and  system  cpu  time  alone  (both 
in  minutes)  will  sometimes  appear. 

OPTIONS 

a  Place  all  command  names  containing  unprintable  characters  and  those  used  only  once 

under  the  name  ‘♦**other.’ 

b  Sort  output  by  sum  of  user  and  system  time  divided  by  number  of  calls.  Default  sort  is 

by  sum  of  user  and  system  times. 

c  Besides  total  user,  system,  and  real  time  for  each  command  print  percentage  of  total 

time  over  all  commands. 

d  Sort  by  average  number  of  disk  I/O  operations. 

D  Print  and  sort  by  total  number  of  disk  I/O  operations, 
f  Force  no  interactive  threshold  compression  with  — v  flag, 

i  Don’t  read  in  summary  file. 

j  Instead  of  total  minutes  time  for  each  category,  give  seconds  per  call, 

k  Sort  by  cpu-time  average  memory  usage. 

K  Print  and  sort  by  cpu-storage  integral. 

1  Separate  system  and  user  time;  normally  they  are  combined, 

m  Print  number  of  processes  and  number  of  CPU  minutes  for  each  user, 
n  Sort  by  number  of  calls, 

r  Reverse  order  of  sort, 

s  Merge  accounting  file  into  summary  file  /usr/adm/savacct  when  done, 

t  For  each  command  report  ratio  of  real  time  to  the  sum  of  user  and  system  times. 

u  Superseding  all  other  Bags,  print  for  each  record  in  the  accounting  file  the  user  ID  and 
command  name. 
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V  Followed  by  a  number  n,  types  the  name  of  each  command  used  n  times  or  fewer.  Await 
a  reply  from  the  terminal;  if  it  begins  with  ‘y’,  add  the  command  to  the  category 
‘**junk**.’  This  is  used  to  strip  out  garbage. 

FILES 

/usr/adm/acct  raw  accounting 

SEE  ALSO 

ac(8),  acct(2),  acct(5) 
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NAME 

savecore  —  save  a  core  dump  of  the  operating  system 
SYNOPSIS 

/usr/etc/Bavecore  dirname  (  system  ] 

DESCRIPTION 

Savecore  is  meant  to  be  called  near  the  end  of  the  /etcfro  file  after  the  system  boots.  Savecore^s 
function  is  to  save  the  core  dump  of  the  system  (assuming  one  was  made)  and  to  write  a  reboot 
message  in  the  shutdown  log. 

Savecore  checks  the  core  dump  to  be  certain  it  corresponds  with  the  current  running  version  of 
the  operating  system.  If  it  does,  savecore  saves  the  core  image  in  the  file  rftrname /vmcore.n  and 
its  brother,  the  namelist,  rftrname/vmunix.n  The  trailing  .n  in  the  pathnames  is  replaced  by  a 
number  which  grows  every  time  savecore  is  run  in  that  directory. 

Before  savecore  writes  out  a  core  image,  it  reads  a  number  from  the  file  dtrname/minfree.  If 
there  less  free  space  on  the  filesystem  which  contains  dirname  than  the  number  obtained  from 
the  minfree  file,  the  core  dump  is  not  done.  If  the  minfree  file  does  not  exist,  savecore  always 
writes  out  the  core  file  (assuming  that  a  core  dump  was  taken). 

Savecore  also  writes  a  reboot  message  in  the  shut  down  log.  If  the  system  crashed  as  a  result  of 
a  panic,  savecore  records  the  panic  string  in  the  shut  down  log  too. 

If  the  core  dump  was  from  a  system  other  than  /vmunix,  the  name  of  that  system  must  be  sup¬ 
plied  as  sysname. 

FILES 

/usr/adm/shutdownlog  shut  down  log 
/usr/crash/bounds  number  to  assign  to  the  core  images 

/vmunix  current  UNIX 

BUGS 

Can  be  fooled  into  thinking  a  core  dump  is  the  wrong  size. 
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NAME 

sendmail  —  send  mail  over  the  internet 


SYNOPSIS 

/usr /lib /send  mall  [  — ba  j  [  — bd  ]  [  — bl  |  [  — bm  |  (  —bp  ]  ]  — bs  ]  [  — bt  j  [  — bv  ] 

I  -Cfile  I  I  -dX  I  [  -TfuUname  |  |  -fname  ]  j  -hN  ]  [  -n  ]  (  -ox  value  |  [  -q[  time  |  ) 

[  —rname  |  [  — t  ]  [  — v  [  [  address  •••  ] 

DESCRIPTION 

Sendmail  sends  a  message  to  one  or  more  people,  routing  the  message  over  whatever  networks 
are  necessary.  Sendmail  does  internetwork  forwarding  as  necessary  to  deliver  the  message  to  the 
correct  place. 

Sendmail  is  not  intended  as  a  user  Interface  routine;  other  programs  provide  user-friendly  front 
ends;  sendmail  is  used  only  to  deliver  pre-formatted  messages. 

With  no  flags,  sendmail  reads  its  standard  input  up  to  a  control-D  or  a  line  with  a  single  dot  and 
sends  a  copy  of  the  letter  found  there  to  all  of  the  addresses  listed.  It  determines  the  network  to 
use  based  on  the  syntax  and  contents  of  the  addresses. 

Local  addresses  are  looked  up  in  a  file  and  aliased  appropriately.  Aliasing  can  be  prevented  by 
preceding  the  address  with  a  backslash.  Normally  the  sender  is  not  included  in  any  alias  expan¬ 
sions,  for  example,  if  ‘john’  sends  to  ‘group’,  and  ‘group’  includes  ‘john’  in  the  expansion,  then 
the  letter  will  not  be  delivered  to  *john’. 


OPTIONS 

— ba 


-bd 


Go  into  ARPANET  mode.  All  input  lines  must  end  with  a  CR-LF,  and  all 
messages  will  be  generated  with  a  CR-LF  at  the  end.  Also,  the  “From:”  and 
‘‘Sender:’’  fields  are  examined  for  the  name  of  the  sender. 

Run  as  a  daemon,  waiting  for  incoming  SMTP  connections. 


-bl 
— bm 
-bp 
— bs 

-bt 

— bv 

-Cfile 

-dX 


Initialize  the  alias  database. 

Deliver  mail  in  the  usual  way  (default). 

Print  a  summary  of  the  mail  queue. 

Use  the  SMTP  protocol  as  described  in  RFC821.  This  flag  implies  all  the 
operations  of  the  — ba  flag  that  are  compatible  with  SMTP. 

Run  in  address  test  mode.  This  mode  reads  addresses  and  shows  the  steps  in 
parsing;  it  is  used  for  debugging  configuration  tables. 

Verify  names  only  —  do  not  try  to  collect  or  deliver  a  message.  Verify  mode 
is  normally  used  for  validating  users  or  mailing  lists. 

Use  alternate  configuration  file. 

Set  debugging  value  to  X 


—Ffullname 
— fname 

-hAT 


-Mid 


Set  the  full  name  of  the  sender. 

Sets  the  name  of  the  “from”  person  (that  is,  the  sender  of  the  mail).  — f  can 
only  be  used  by  “trusted”  users  (who  are  listed  in  the  config  file). 

Set  the  hop  count  to  N,  The  hop  count  is  incremented  every  time  the  mail  is 
processed.  When  it  reaches  a  limit,  the  mail  is  returned  with  an  error  mes¬ 
sage,  the  victim  of  an  aliasing  loop. 

Attempt  to  deliver  the  queued  message  with  message-id  Id. 


— n 

—ox  value 
— q[  time  [ 


Don’t  do  aliasing. 

Set  option  x  to  the  specified  value.  Options  are  described  below. 

Processed  saved  messages  in  the  queue  at  given  intervals.  If  time  is  omitted, 
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—rname 
—R  string 


-t 


— V 


process  the  queue  once.  Time  is  given  as  a  tagged  number,  with  V  being 
seconds,  ‘m*  being  minutes,  ‘h*  being  hours,  ‘d’  being  days,  and  ‘w’  being 
weeks.  For  example,  “-qlh30m”  or  “-q90m”  would  both  set  the  timeout  to 
one  hour  thirty  minutes. 

An  alternate  and  obsolete  form  of  the  — f  flag. 

Go  through  the  queue  of  pending  mail  and  attempt  to  deliver  any  message 
with  a  recipient  containing  the  specified  string.  This  is  useful  for  clearing  out 
mail  directed  to  a  machine  which  has  been  down  for  awhile. 

Read  message  for  recipients.  To:,  Cc:,  and  Bcc:  lines  will  be  scanned  for  peo¬ 
ple  to  send  to.  The  Bcc:  line  will  be  deleted  before  transmission.  Any 
addresses  in  the  argument  list  will  be  suppressed. 

Go  into  verbose  mode.  Alias  expansions  will  be  announced,  etc. 


PROCESSING  OPTIONS 

There  are  also  a  number  of  processing  options  that  may  be  set.  Normally  these  will  only  be  used 
by  a  system  administrator.  Options  may  be  set  either  on  the  command  line  using  the  — o  flag  or 
in  the  configuration  file.  These  are  described  in  detail  in  the  Installation  and  Operation  Guide, 
The  options  are: 


Afile 

c 

dx 


D 

ez 


Fmode 

f 

gN 

Ufile 

i 

hn 

m 

o 


Qqueuedir 

rtimeout 

Sfile 


Use  alternate  alias  file. 

On  mailers  that  are  considered  “expensive”  to  connect  to,  don’t  initiate 
immediate  connection.  This  requires  queueing. 

Set  the  delivery  mode  to  z.  Delivery  modes  are  'i’  for  interactive  (synchro¬ 
nous)  delivery,  *b’  for  background  (asynchronous)  delivery,  and  *q’  for  queue 
only  —  that  is,  actual  delivery  is  done  the  next  time  the  queue  is  run. 

Try  to  automatically  rebuild  the  alias  database  if  necessary. 

Set  error  processing  to  mode  x.  Valid  modes  are  'm’  to  mail  back  the  error 
message,  ‘w*  to  “write”  back  the  error  message  (or  mail  it  back  if  the  sender 
is  not  logged  in),  ‘p*  to  print  the  errors  on  the  terminal  (default),  ‘q’  to  throw 
away  error  messages  (only  exit  status  is  returned),  and  ‘e*  to  do  special  pro¬ 
cessing  for  the  BerkNet.  If  the  text  of  the  message  is  not  mailed  back  by 
modes 'm*  or  ‘w*  and  if  the  sender  is  local  to  this  machine,  a  copy  of  the  mes¬ 
sage  is  appended  to  the  file  “dead.letter”  in  the  sender’s  home  directory. 

The  mode  to  use  when  creating  temporary  files. 

Save  UNK-style  From  lines  at  the  front  of  messages. 

The  default  group  id  to  use  when  calling  mailers. 

The  SMTP  help  file. 

Do  not  take  dots  on  a  line  by  themselves  as  a  message  terminator. 

The  log  level. 

Send  to  “me”  (the  sender)  also  if  I  am  in  an  alias  expansion. 

If  set,  this  message  may  have  old  style  headers.  If  not  set,  this  message  is 
guaranteed  to  have  new  style  headers  (that  is,  commas  instead  of  spaces 
between  addresses).  If  set,  an  adaptive  algorithm  is  used  that  will  correctly 
determine  the  header  format  in  most  cases. 

Select  the  directory  in  which  to  queue  messages. 

The  timeout  on  reads;  if  none  is  set,  sendmail  will  wait  forever  for  a  mailer. 
Save  statistics  in  the  named  file. 
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s  Always  instantiate  the  queue  file,  even  under  circumstances  where  it  is  not 

strictly  necessary. 

Ttime  Set  the  timeout  on  messages  in  the  queue  to  the  specified  time.  After  sitting 

in  the  queue  for  this  amount  of  time,  they  will  be  returned  to  the  sender. 
The  default  is  three  days. 

istZfdiz  Set  the  name  of  the  time  zone. 

\xN  Set  the  default  user  id  for  mailers. 

If  the  first  character  of  the  user  name  is  a  vertical  bar,  the  rest  of  the  user  name  is  used  as  the 
name  of  a  program  to  pipe  the  mail  to.  It  may  be  necessary  to  quote  the  name  of  the  user  to 
keep  sendmail  from  suppressing  the  blanks  from  between  arguments. 

Sendmail  returns  an  exit  status  describing  what  it  did.  The  codes  are  defined  in 
EX_OK  Successful  completion  on  all  addresses. 

EXJVOUSER  User  name  not  recognized. 

EX^UNAVAILABLE  Catchall  meaning  necessary  resources  were  not  available. 

EX^SYNTAX  Syntax  error  in  address. 

EX_SOFTWARE  Internal  software  error,  including  bad  arguments. 

EX_OSERR  Temporary  operating  system  error,  such  as  “cannot  fork”. 

EX_NOHOST  Host  name  not  recognized. 

EX_TEMPFAIL  Message  could  not  be  sent  immediately,  but  was  queued. 

If  invoked  as  newaliaseB,  sendmail  rebuilds  the  alias  database.  If  invoked  as  mailq,  sendmail 
prints  the  contents  of  the  mail  queue. 

FILES 

Except  for  /usr/lib/sendmaiLcf,  these  pathnames  are  all  specified  in  /nsr/lib/sendmaii.cf.  Thus, 
these  values  are  only  approximations. 

/usr /lib/aliases  raw  data  for  alias  names 

/usr /lib/aliases. pag 

/usr /lib/aliases. dir  data  base  of  alias  names 

/usr/lib/sendmail.cf  configuration  file 

/usr/lib/sendmail.fc  frozen  configuration 

/usr/lib/sendmail.hf  help  file 

/usr/lib/sendmail.st  collected  statistics 

/usr/bin/uux  to  deliver  uucp  mail 

/bin/mail  to  deliver  local  mail 

/usr/spool/mqueue/»  temp  files  and  queued  mail 

"/.mailcf  Individual  users*  configuration  file 

SEE  ALSO 

biff(l),  binmail(l),  mail(l),  aliases(5), 

DARPA  Internet  Request  For  Comments  RFC819,  RFC821,  RFC822, 

In  the  System  Manager's  Manual: 

Setting  Up  the  Mail  System  in  the  System  SeUup  and  Operation  chapter. 

Sendmail  —  An  Internetwork  Mail  Router,  in  the  Tutorials  section 
Sendmail  Installation  and  Operation  Guide,  in  the  Tutorials  section 

BUGS 

Sendmail  converts  blanks  in  addresses  to  dots.  This  is  incorrect  according  to  the  old  ARPANET 
mail  protocol  RFC733  (NIC  41952),  but  is  consistent  with  the  new  protocols  (RFC822). 


688 


Last  change:  5  November  1984 


Sun  Release  2.0 


SENDNEWS(8) 


MAINTENANCE  COMMANDS 


SENDNEWS(8) 


NAME 

sendnews  —  send  news  articles  via  mail 
SYNOPSIS 

sendnews  |  — o  ]  [  —a  ]  (  — b  [  |  — n  newsgroups  j  destination 
DESCRIPTION 

stndntws  reads  an  article  from  it’s  standard  input,  performs  a  set  of  changes  to  it,  and  gives  it  to 
the  mail  program  to  mail  it  to  destination. 

An  ‘N'  is  prepended  to  each  line  for  decoding  by  u«rec(l). 

OPTIONS 

— o  handle  old  format  articles. 

—a  used  for  sending  articles  via  the  ARPANET.  It  maps  the  article’s  path  from  uucphostlxxx 
to  xxx@arpaho$t, 

— b  used  for  sending  articles  via  the  Berknet.  It  maps  the  article’s  path  from  uucphostlxxx 

to  berkhostixxx, 

—n  change  the  article’s  newsgroup  to  the  specified  newsgroup, 

SEE  ALSO 

inews(l),  uurec(8),  recnews(8),  readnews(l),  checknews(l) 
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NAME 

showmount  —  show  all  remote  mounts 
SYNOPSIS 

showmount  [  — a  |  [  — d  ]  [  — e  j  [  host  ] 

DESCRIPTION 

Showmount  lists  all  the  clients  that  have  remotely  mounted  a  filesystem  from  host.  This  infor¬ 
mation  is  maintained  by  the  mountd{Sc)  server  on  hostf  and  is  saved  across  crashes  in  the  file 
/etc/rmtab.  The  default  value  for  host  is  the  value  returned  by  hoetnam€[l), 

OPTIONS 

— d  List  directories  that  have  been  remotely  mounted  by  clients. 

—a  Print  all  remote  mounts  in  the  format 
hostname:directory 

where  hostname  is  the  name  of  the  client,  and  directory  is  the  root  of  the  file  system  that 
has  been  mounted. 

— e  Print  the  list  of  exported  file  systems. 

SEE  ALSO 

rmtab(5),  mountd(8),  exports(5) 

BUGS 

If  a  client  crashes,  its  entry  will  not  be  removed  from  the  list  until  it  reboots  and  executes 
amount  —a. 
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NAME 

shutdown  —  close  down  the  system  at  a  given  time 
SYNOPSIS 

/etc/shutdown  |  — k  ]  |  — r  ]  [  — h  ]  time  [  warning-message  ] 

DESCRIPTION 

Shutdown  provides  an  automated  shutdown  procedure  for  the  super- user  to  notify  users  politely 
when  the  system  is  shutting  down.  Time  specifies  when  shutdown  will  bring  the  system  down;  it 
may  be  the  word  now  (indicating  an  immediate  shutdown),  or  it  may  specify  a  future  time  in  one 
of  two  formats:  -|-num^er  and  hourtmin.  The  first  form  brings  the  system  down  in  number 
minutes,  and  the  second  brings  the  system  down  at  the  time  of  day  indicated  in  24-hour  notation. 

At  intervals  that  get  closer  as  the  apocalypse  approaches,  warning  messages  are  displayed  at  ter¬ 
minals  of  all  logged-in  users,  and  of  users  who  have  remote  mounts  on  that  machine.  Five 
minutes  before  shutdown,  or  immediately  if  shutdown  is  in  less  than  5  minutes,  logins  are  dis¬ 
abled  by  creating  ( etc/ nologin  and  writing  a  message  there.  If  this  file  exists  when  a  user 
attempts  to  log  in,  login{l)  prints  its  contents  and  exits.  The  file  is  removed  Just  before  shut¬ 
down  exits. 

At  shutdown  time  a  message  is  written  in  the  file  ( ust! adm/ shutdownlog ^  containing  the  time  of 
shutdown,  the  instigator  of  the  shutdown,  and  the  reason.  Then  a  terminate  signal  is  sent  to 
init,  which  brings  the  system  down  to  single-user  mode. 

The  time  of  the  shutdown  and  the  warning  message  are  placed  in  /etc/nologin,  which  should  be 
used  to  inform  the  users  as  to  when  the  system  will  be  back  up,  and  why  it  is  going  down  (or 
anything  else). 

OPTIONS 

As  an 

— r 
-h 
-k 

FILES 

/etc/nologin  tells  login  not  to  let  anyone  log  in 
/usr/adm/shutdownlog  log  file  for  succesful  shutdowns. 

SEE  ALSO 

login(l),  reboot(8) 

BUGS 

Only  allows  you  to  kill  the  system  between  now  and  23:59  if  you  use  the  absolute  time  for  shut¬ 
down.  @(#)skyversion.8  1.3  85/04/05  SMI 


alternative  to  the  above  procedure,  these  options  can  be  specified: 

Execute  r€boot{S). 

Execute  halt{S), 

Make  people  think  the  system  is  going  down,  but  do  not  actually  take  it  down. 
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NAME 

sky  version  -  print  the  SKYFFP  board  microcode  version  number 

SYNOPSIS 

/uBr/etc  /Bkyverslon 

DESCRIPTION 

akyversion  obtains  from  the  SKYFFP  board  the  Sky  version  number  of  the  microcode  currently 
loaded  and  prints  the  result  on  the  standard  output. 

DIAGNOSTICS 

The  Sky  version  number  operation  code  used  to  implement  this  command  is  not  available  for 
microcode  releases  earlier  than  Sky  release  3.00.  The  result  in  this  case  is  unpredictable  and  is 
either  a  nonmeaningful  version  number  or  a  message  indicating  that  no  version  number  is  avail¬ 
able.  Meaningful  version  numbers  are  of  the  form  n.dd  where  n  >  3. 
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NAME 

sticky  —  executable  files  with  persistent  text 
DESCRIPTION 

While  the  ‘sticky  bit’,  mode  01000  (see  chmod(2)),  is  set  on  a  sharable  executable  file,  the  text  of 
that  file  will  not  be  removed  from  the  system  swap  area.  Thus  the  file  does  not  have  to  be 
fetched  from  the  file  system  upon  each  execution.  As  long  as  a  copy  remains  in  the  swap  area, 
the  original  text  cannot  be  overwritten  in  the  file  system,  nor  can  the  file  be  deleted.  Directory 
entries  can  be  removed  so  long  as  one  link  remains. 

Sharable  files  are  made  by  the  — »  option  of  W(l). 

To  replace  a  sticky  file  that  has  been  used  do:  (1)  Clear  the  sticky  bit  with  cAtnod(l).  (2)  Exe¬ 
cute  the  old  program  to  flush  the  swapped  copy.  This  can  be  done  safely  even  if  others  are  using 
it.  (3)  Overwrite  the  sticky  file.  If  the  file  is  being  executed  by  any  process,  writing  will  be 
prevented;  it  suffices  to  simply  remove  the  file  and  then  rewrite  it,  being  careful  to  reset  the 
owner  and  mode  with  ehmod  and  chou)n{2).  (4)  Set  the  sticky  bit  again. 

Only  the  super-user  can  set  the  sticky  bit. 
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NAME 

swapon  —  specify  additional  device  for  paging  and  swapping 
SYNOPSIS 

/uar/etc/swapon  —a 
/usr/etc/Bwapon  name  ... 

DESCRIPTION 

Swapon  is  used  to  specify  additional  devices  on  which  paging  and  swapping  are  to  take  place. 
The  system  begins  by  swapping  and  paging  on  only  a  single  device  so  that  only  one  disk  is 
required  at  bootstrap  time.  Calls  to  swapon  normally  occur  in  the  system  multi-user  initializa¬ 
tion  file  /etc/rc  making  all  swap  devices  available,  so  that  the  paging  and  swapping  activity  is 
interleaved  across  several  devices. 

Normally,  the  —a  argument  is  given,  causing  all  devices  marked  as  "sw"  swap  devices  in 
/ete/fstab  to  be  made  available. 

The  second  form  gives  individual  block  devices  as  given  in  the  system  swap  configuration  table. 
The  call  makes  only  this  space  available  to  the  system  for  swap  allocation. 

SEE  ALSO 

swapon(2),  init(8) 

FILES 

/dev/|ru]|pk]?b  normal  paging  devices 

BUGS 

There  is  no  way  to  stop  paging  and  swapping  on  a  device.  It  is  therefore  not  possible  to  make 
use  of  devices  which  may  be  dismounted  during  system  operation. 
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NAME 

sync  —  update  the  super  block 

SYNOPSIS 

sync 

DESCRIPTION 

Sync  executes  the  sync  system  primitive.  Sync  can  be  called  to  insure  all  disk  writes  have  been 
completed  before  the  processor  is  halted  in  a  way  not  suitably  done  by  reboot{S)  or  ^att(8). 

See  5^nc(2)  for  details  on  the  system  primitive. 

SEE  ALSO 

sync(2),  fsync(2),  halt(8),  reboot(8) 
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NAME 

sysdiag  —  system  diagnostics 
SYNOPSIS 

/usr/dlag/sysdtag/syBdiag 

DESCRIPTION 

Sysdiag  is  a  general-purpose  system  diagnostic  facility  that  tests  the  system  and  reports  its 
findings.  It  concentrates  on  three  areas  of  system  functionality;  memory,  peripherals  and  disk. 

To  use  sysdiag,  log  on  as  sysdiag,  then  enter  the  command  sysdiag. 

Sysdiag  creates  a  S untools  environment  with  one  window  each  for  memory,  peripherals,  and  disk 
error  messages,  plus  a  window  for  the  console.  It  also  creates  date/time  and  performance  moni¬ 
tor  graphs.  It  places  abbreviated  error  messages  from  the  memory,  disk,  and  peripherals  in  the 
appropriate  windows,  and  sends  console  messages  to  the  console  window. 

When  called  from  a  terminal  sysdiag  interleaves  all  its  messages  on  the  screen. 

With  or  without  the  windows,  it  places  long  error  messages  in  files  named  log*xx.nn  where: 

XX  is  the  name  of  diagnostic 

nn  is  the  pass  number  (increments  each  pass) 

After  it  completes  its  test,  sysdiag  displays  the  error  log  files  by  executing  the  command 
more  log*.  These  files  remain  after  sysdiag  exits, 

Sysdiag  consists  of  a  user  account  with  a  home  directory,  a  collection  of  scripts,  and  executable 
files  containing  the  actual  test  code. 

To  configure  or  change  sysdiag,  either  change  the  shell  commands  in  / usr/ diag/ sysdiag/ sysdiag , 
or  change  the  sysdiag  user  configuration  files  Jogin,  ^suntools,  and  .cshrc. 

SEE  ALSO 

Sun‘£/160  Diagnostics  Manual  and  Sun-S/120  Diagnostics  Manual. 
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NAME 

syslog  —  log  systems  messages 
SYNOPSIS 

/uar/etc/ln.syBlog  [  — mN]  [  — fntime  [  |  —d  |  (  — p  port  j 
DESCRIPTION 

Sydog  reads  a  datagram  socket  and  logs  each  message  it  reads  into  a  set  of  files  described  by  the 
configuration  file  /eicisyslogxonf.  Syslog  configures  when  it  starts  up  and  whenever  it  receives  a 
hangup  signal.  Syslog  logs  to  the  host  specified  by  'loghosV  in  the  j stcf  hosts  file.  For  details  on 
running  syslog  in  a  Sun  network  environment,  see  the  section,  “System  Log  Configuration”  in  the 
SysUm  Set-up  and  Operation  chapter  of  the  System  Installation  and  Maintenance  Guide, 

Each  message  logged  consists  of  one  line.  A  message  can  contain  a  priority  code,  marked  by  a 
digit  in  angle  braces  at  the  beginning  of  the  line.  Priorities  are  defined  in  <syslog.h>,  as  defined 
in  the  list  below.  LOG^LERT  is  prioity  1  (the  highest  priority)  while  LOG J)EBUG  is  priority 
9  (the  lowest  priority). 

LOG^ALERT  this  priority  should  essentially  never  be  used.  It  applies  only  to  messages  that 
are  so  important  that  every  user  should  be  aware  of  them,  for  example,  a 
serious  hardware  failure. 

messages  of  this  priority  should  be  issued  only  when  immediate  attention  is 
needed  by  a  qualified  system  person,  for  example,  when  some  valuable  system 
resource  disappears.  They  get  sent  to  a  list  of  system  people. 

Emergency  messages  are  not  sent  to  users,  but  represent  major  conditions. 
An  example  might  be  hard  disk  failures.  These  could  be  logged  in  a  separate 
file  so  that  critical  conditions  could  be  easily  scanned. 

these  represent  error  conditions,  such  as  soft  disk  failures,  etc. 

such  messages  contain  critical  information,  but  which  can  not  be  classed  as 
errors,  for  example,  ‘su’  attempts.  Messages  of  this  priority  and  higher  are 
typically  logged  on  the  system  console. 

issued  when  an  abnormal  condition  has  been  detected,  but  recovery  can  take 
place. 

LOG_NOTICE  something  that  falls  in  the  class  of  “important  information;”  this  class  is 
informational  but  important  enough  that  you  don’t  want  to  throw  items  in  it 
away  casually.  Messages  without  any  priority  assigned  to  them  are  typically 
mapped  into  this  priority. 

LOGJNFO  information  level  messages.  These  messages  could  be  thrown  away  without 

problems,  but  should  be  included  if  you  want  to  keep  a  close  watch  on  your 
system, 

LOGJ)EBUG  it  may  be  useful  to  log  certain  debugging  information.  Normally  this  will  be 
thrown  away. 

It  is  expected  that  the  kernel  will  not  log  anything  below  LOG  J)RR  priority. 

The  syslog  configuration  file,  etc/ syslog, conf,  consists  of  two  sections  separated  by  a  blank  line. 
The  first  section  defines  files  that  syslog  will  log  into.  Each  line  contains  a  single  digit  which 
defines  the  lowest  priority  (highest  numbered  priority)  that  this  file  will  receive,  an  optional 
asterisk  which  guarantees  that  something  gets  output  at  least  every  20  minutes,  and  a  pathname. 
The  second  part  of  the  file  contains  a  list  of  users  that  will  be  informed  on  SALERT  level  mes¬ 
sages.  For  example,  the  configuration  file: 

5^/dev/tty8 
8/  usr  /s  pool/ad  m/sy  slog 


LOG_SALERT 

logj:merg 

logj:rr 

LOG_CRIT 

log^warning 
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3/usr/adm/critical 

eric 

kridle 

kalash 

logs  all  messages  of  priority  5  or  higher  onto  the  system  console,  including  timing  marks  every  20 
minutes;  all  messages  of  priority  8  or  higher  into  the  file  /u$r/ spool/ adm/eyalog;  and  all  messages 
of  priority  3  or  higher  into  /usr/adm/ critical.  The  users  ‘eric’,  ‘kridle’,  and  ‘kalash’  wilt  be 
informed  on  any  subalert  messages. 

OPTIONS 

-xniV  Set  the  mark  interval  to  N  (default  20  minutes). 

— f  nome 

Specify  an  alternate  configuration  file. 

— d  Turn  on  debugging  (if  compiled  in). 

—pport 

Port  number  where  ayslog  listens  for  incoming  datagrams.  The  default  port  is  defined  in 
the  ‘syslog/udp’  entry  in  the  /etc/ services  file. 

To  bring  syslog  down,  it  should  be  sent  a  terminate  signal.  It  logs  that  it  is  going  down  and  then 
waits  approximately  10  seconds  for  any  additional  messages  to  come  in. 

There  are  some  special  messages  that  cause  control  functions.  ‘<*>N’  sets  the  default  message 
priority  to  N.  '<$>’  causes  syslog  to  reconfigure  (equivalent  to  a  hangup  signal).  This  can  be 
used  in  a  shell  file  run  automatically  early  in  the  morning  to  truncate  the  log. 

Syslog  creates  the  file  /etc/syslog.pid  if  possible  containing  a  single  line  with  its  process  id.  This 
can  be  used  to  kill  or  reconfigure  syslog. 

FILES 

/etc/hosts  —  the  hosts  file 
/etc/syslog.conf  —  the  configuration  file 
/etc/syslog.pid  —  the  process  id 

/etc/services  —  to  find  the  syslog  server’s  port  number. 

BUGS 

LOG_ALERT  and  LOG_SALERT  messages  should  only  be  allowed  to  privileged  programs. 

Actually,  syslog  is  not  clever  enough  to  deal  with  kernel  error  messages  in  the  current  implemen¬ 
tation. 

SEE  ALSO 

syslog(3),  kill(2) 
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NAME 

talkd  —  server  for  talk  program 

SYNOPSIS 

/  usr  /etc /installed 

DESCRIPTION 

Talkd  is  a  server  used  by  talk(l)  program.  It  listens  at  the  udp  port  indicated  in  the  “talk’’ 
service  description;  see  5ermce^(5).  The  actual  conversation  takes  place  on  a  tep  connection  that 
is  established  by  negotiation  between  the  two  machines  involved. 

SEE  ALSO 

services(5),  talk(l),  inetd(8) 

BUGS 

The  protocol  is  architecture  dependent,  and  can’t  be  relied  upon  to  work  between  Suns  and  other 
machines. 
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NAME 

telnetd  —  DARPA  TELNET  protocol  server 
SYNOPSIS 

/usr /etc /in. telnetd  host. port 
DESCRIPTION 

Telnetd  is  a,  server  which  supports  the  DARPA  standard  TELNET  virtual  terminal  protocol. 
The  TELNET  server  is  invoked  by  f«eW(8C)  each  time  there  is  a  connection  to  the  telnet  ser¬ 
vice;  see  ^en;fce^(5). 

Telnetd  operates  by  allocating  a  pseudo-terminal  device  (see  pty{4))  for  a  client,  then  creating  a 
login  process  which  has  the  slave  side  of  the  pseudo-terminal  as  stdln,  stdout,  and  stderr.  Tel* 
netd  manipulates  the  master  side  of  the  pseudo  terminal,  implementing  the  TELNET  protocol 
and  passing  characters  between  the  client  and  login  process. 

When  a  TELNET  session  is  started  up,  telnetd  sends  a  TELNET  option  to  the  client  side  indicat¬ 
ing  a  willingness  to  do  “remote  echo”  of  characters.  The  pseudo  terminal  allocated  to  the  client 
is  configured  to  operate  in  “cooked”  mode,  and  with  XTABS  and  CRMOD  enabled  (see  ity{4)). 
Aside  from  this  initial  setup,  the  only  mode  changes  telnetd  will  carry  out  are  those  required  for 
echoing  characters  at  the  client  side  of  the  connection. 

Telnetd  supports  binary  mode,  and  most  of  the  common  TELNET  options,  but  does  not,  for 
instance,  support  timing  marks. 

SEE  ALSO 

telnet(lC) 

BUGS 

A  complete  list  of  the  options  supported  should  be  given  here. 
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TFTPD(8C) 


NAME 

tftpd  —  DARPA  Trivial  File  Transfer  Protocol  server 
SYNOPSIS 

/u8r/etc/ln.tftpd  [  — d  |  [  port  ] 

DESCRIPTION 

Tftpd  is  a  server  which  supports  the  DARPA  Trivial  File  Transfer  Protocol.  The  TFTP  server 
operates  at  the  port  indicated  in  the  “tftp”  service  description;  see  9ervices[&),  and  is  invoked 
each  time  a  datagram  reaches  this  port  by  the  internet  server  >ne(d(8C). 

Due  to  the  lack  of  authentication  information,  tftpd  will  allow  only  publicly  readable  files  to  be 
accessed.  To  do  this,  tftpd  executes  as  uid  —2,  gid  -2  ,  assuming  that  no  files  exist  with  that 
owner  or  group.  However,  nothing  check  this  assumption  or  enforces  this  restriction. 

SEE  ALSO 

tftp(lC) 

BUGS 

This  server  is  known  only  to  be  self  consistent  (i.e.  it  operates  with  the  user  TFTP  program, 
tftp[\C)). 
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TIMED  (8C) 


NAME 

timed  —  DARPA  Time  server 


SYNOPSIS 

f  usr  /etc/in.tlmed 

DESCRIPTION 

Timed  is  a  server  which  supports  the  DARPA  Time  Server  Protocol.  The  time  server  operates 
at  the  port  indicated  in  the  “time”  service  description;  see  «ervtcc«(5),  and  is  invoked  by 
meW(8C)  each  time  there  is  a  connection  to  the  time  server. 


SEE  ALSO 

services(5),  rdate(8),  inetd(8) 


BUGS 


A  more  sophisticated  facility  that  can  accept  broadcasts  and  synchronize  clocks  over  an  internet 
is  needed. 


602 


Last  change:  13  Dec  1983 


Sun  Release  2.0 


TRPT(8C) 


MAINTENANCE  COMMANDS 


TRPT(8C) 


NAME 

trpt  —  transliterate  protocol  trace 
SYNOPSIS 

/u8r/etc/trpt  [  -a  j  [  — s  |  |  — t  ]  (  — J  |  (  -phtx-addrtss )  [  system  (  core  ]  | 

DESCRIPTION 

Trpi  interrogates  the  buffer  of  TCP  trace  records  created  when  a  socket  is  marked  for  ‘debug¬ 
ging’  (see  $€t8ockopi{2)),  and  prints  a  readable  description  of  these  records.  When  no  options  are 
supplied,  trpt  prints  all  the  trace  records  found  in  the  system  grouped  according  to  TCP  connec¬ 
tion  protocol  control  block  (PCB). 

OPTIONS 

— s  Print  a  detailed  description  of  the  packet  sequencing  information,  in  addition  to  the  nor¬ 

ma!  output. 

— t  Print  the  values  for  all  timers  at  each  point  in  the  trace,  in  addition  to  the  normal  out¬ 

put, 

— j  Just  give  a  list  of  the  protocol  control  block  addresses  for  which  there  are  trace  records. 

—pheX‘addre88 

Show  only  trace  records  associated  with  the  protocol  control  block  who’s  address  follows. 

—a  in  addition  to  the  normal  output,  print  the  values  of  the  source  and  destination 
addresses  for  each  packet  recorded. 

The  recommended  use  of  trpt  is  as  follows.  Isolate  the  problem  and  enable  debugging  on  the 
socket(s)  involved  in  the  connection.  Find  the  address  of  the  protocol  control  blocks  associated 
with  the  sockets  using  the  —A  option  to  Then  run  trpt  with  the  — p  option,  supplying 

the  associated  protocol  control  block  addresses.  If  there  are  many  sockets  using  the  debugging 
option,  the  — j  option  may  be  useful  in  checking  to  see  if  any  trace  records  are  present  for  the 
socket  in  question. 

If  debugging  is  being  performed  on  a  system  or  core  file  other  than  the  default,  the  last  two  argu¬ 
ments  may  be  used  to  supplant  the  defaults. 

FILES 

/vmunix 

/dev/kmem 

SEE  ALSO 

setsockopt(2),  netstat(8) 

DIAGNOSTICS 

‘no  namelist’  when  the  system  image  doesn’t  contain  the  proper  symbols  to  find  the  trace  buffer; 
others  which  should  be  self  explanatory. 

BUGS 

Should  also  print  the  data  for  each  input  or  output,  but  this  is  not  saved  in  the  trace  record. 

The  output  format  is  inscrutable,  and  should  be  described  here. 
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TUNEFS(8) 


NAME 

tunefs  —  tune  up  an  existing  file  system 
SYNOPSIS 

/etc/tunefs  [  —a  maxconiig  j  [  — d  rotdelay  |  [  — e  maxbpg  ]  [  — m  minfree  ]  special  [  fileeys 
DESCRIPTION 

Tunefs  is  designed  to  change  the  dynamic  parameters  of  a  file  system  which  affect  the  layout  pol¬ 
icies.  The  parameters  which  are  to  be  changed  are  indicated  by  the  flags  given  below: 

—a  maxcontig 

This  specifies  the  maximum  number  of  contiguous  blocks  that  will  be  laid  out  before 
forcing  a  rotational  delay  (see  — d  below).  The  default  value  is  one,  since  most  device 
drivers  require  an  interrupt  per  disk  transfer.  Device  drivers  that  can  chain  several 
buffers  together  in  a  single  transfer  should  set  this  to  the  maximum  chain  length. 

— d  rotdelay 

This  specifies  the  expected  time  (in  milliseconds)  to  service  a  transfer  completion  inter¬ 
rupt  and  initiate  a  new  transfer  on  the  same  disk.  It  is  used  to  decide  how  much  rota¬ 
tional  spacing  to  place  between  successive  blocks  in  a  file. 

— c  maxhpg 

This  indicates  the  maximum  number  of  blocks  any  single  file  can  allocate  out  of  a 
cylinder  group  before  it  is  forced  to  begin  allocating  blocks  from  another  cylinder  group. 
Typically  this  value  is  set  to  about  one  quarter  of  the  total  blocks  in  a  cylinder  group. 
The  intent  is  to  prevent  any  single  file  from  using  up  all  the  blocks  in  a  single  cylinder 
group,  thus  degrading  access  times  for  all  files  subsequently  allocated  in  that  cylinder 
group.  The  effect  of  this  limit  is  to  cause  big  files  to  do  long  seeks  more  frequently  than 
if  they  were  allowed  to  allocate  all  the  blocks  in  a  cylinder  group  before  seeking  else¬ 
where.  For  file  systems  with  exclusively  large  files,  this  parameter  should  be  set  higher. 

— m  minfree 

This  value  specifies  the  percentage  of  space  held  back  from  normal  users;  the  minimum 
free  space  threshold.  The  default  value  used  is  10%.  This  value  can  be  set  to  zero,  how¬ 
ever  up  to  a  factor  of  three  in  throughput  will  be  lost  over  the  performance  obtained  at 
a  10%  threshold.  Note  that  if  the  value  is  raised  above  the  current  usage  level,  users 
will  be  unable  to  allocate  files  until  enough  files  have  been  deleted  to  get  under  the 
higher  threshold. 

SEE  ALSO 

fs(5),  newfs(8),  mkfs(8),  dumpfs(8) 

The  Sun  UNIX  File  System  in  the  Sun  System  Internals  Manual, 

BUGS 

This  program  should  work  on  mounted  and  active  file  systems.  Because  the  super-block  is  not 
kept  in  the  buffer  cache,  the  program  will  only  take  effect  if  it  is  run  on  dismounted  file  systems, 
(if  run  on  the  root  file  system,  the  system  must  be  rebooted) 
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NAME 

update  —  periodically  update  the  super  block 

SYNOPSIS 

/etc/update 

DESCRIPTION 

Update  is  a  program  that  executes  the  8yne{2)  primitive  every  30  seconds.  This  insures  that  the 
file  system  is  fairly  up  to  date  in  case  of  a  crash.  This  command  should  not  be  executed  directly, 
but  should  be  executed  out  of  the  initialization  shell  command  file. 

SEE  ALSO 

sync(2),  sync(8),  init(8) 
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UUCLEAN(8C) 


NAME 

uuclean  —  uucp  spool  directory  clean-up 
SYNOPSIS 

/usr/llb/uucp/uuclean  |  — pprc  ]  |  —ntime  j  (  — m  ] 

DESCRIPTION 

Uuclean  scans  the  spool  directory  for  files  with  the  specified  prefix  and  deletes  all  those  which  are 
older  than  the  specified  number  of  hours. 

OPTIONS 

—ppre  Scan  for  files  with  pre  as  the  file  prefix.  Up  to  10  — p  arguments  may  be  specified.  A 
— p  without  any  pre  following  deletes  all  files  older  than  the  specified  time. 

— nftme  Files  whose  age  is  more  than  time  hours  are  deleted  if  the  prefix  test  is  satisfied  (default 
time  is  72  hours). 

— m  Send  mail  to  the  owner  of  the  file  when  it  is  deleted. 

Uuclean  will  typically  be  started  by  cron(8). 

FILES 

/usr/lib/uucp  directory  with  commands  used  by  uuclean  internally 

/usr/lib/uucp/spool  spool  directory 

SEE  ALSO 

uucp(lC),  uux(lC) 
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NAME 

uurec  —  receive  processed  news  articles  via  mail 

SYNOPSIS 

uurec 

DESCRIPTION 

uurec  reads  news  articles  on  the  standard  input  sent  by  eendnews{8),  decodes  them,  and  gives 
them  to  tne«>«(l)  for  insertion. 

SEE  ALSO 

inews(l),  readnews(l),  recnews(8),  sendnews(8),  newscheck(l) 
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VIPW(8) 


NAME 

vipw  —  edit  the  password  file 

SYNOPSIS 

/etc/vipw 

DESCRIPTION 

Vipw  edits  the  password  file  while  setting  the  appropriate  locks,  and  does  any  necessary  process¬ 
ing  after  the  password  file  is  unlocked.  If  the  password  file  is  already  being  edited,  then  you  will 
be  told  to  try  again  later.  The  vi  editor  will  be  used  unless  the  environment  variable  EDITOR 
indicates  an  alternate  editor.  Vipw  performs  a  number  of  consistency  checks  on  the  password 
entry  for  root,  and  will  not  allow  a  password  file  with  a  “mangled”  root  entry  to  be  installed. 

SEE  ALSO 

chsh(l),  passwd(l),  passwd(5),  adduser(8) 

FILES 

/etc/ptmp 
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VMSTAT(8) 


NAME 

Ymstat  —  report  virtual  memory  statistics 
SYNOPSIS 

vmstat  I  —fsS  ]  I  initrval  [  count  ]  ] 

DESCRIPTION 

Vmstai  delves  into  the  system  and  normally  reports  certain  statistics  kept  about  process,  virtual 
memory,  disk,  trap  and  cpu  activity. 

Without  options,  vmstai  displays  a  one-line  summary  of  the  virtual  memory  activity  since  the 
system  has  been  booted.  If  interval  is  specified,  vmstai  summarizes  activity  over  the  last  interval 
seconds.  If  a  count  is  given,  the  statistics  are  repeated  count  times. 


For  example,  the  following  command  displays  a  summary  of  what  the  system  is  doing  every  five 
seconds.  This  is  a  good  choice  of  printing  interval  since  this  is  how  often  some  of  the  statistics 
are  sampled  in  the  system. 

hal%  ymstat  5 
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The  fields  of  vmstaVs  display  are: 

procs  Reports  the  number  of  processes  in  each  of  the  three  following  states: 
r  in  run  queue 

b  blocked  for  resources  (i/o,  paging,  etc.) 

w  runnable  or  short  sleeper  (<  20  secs)  but  swapped 

memory  Reports  on  usage  of  virtual  and  real  memory.  Virtual  memory  is  considered  active  if  it 
belongs  to  processes  which  are  running  or  have  run  in  the  last  20  seconds, 
avm  number  of  active  virtual  Kbytes 
fre  size  of  the  free  list  in  Kbytes 

page  Reports  information  about  page  faults  and  paging  activity.  The  information  on  each  of 
the  following  activities  is  averaged  each  five  seconds,  and  given  in  units  per  second, 
re  page  reclaims  —  but  see  the  —S  option  for  how  this  field  is  modified, 
at  number  of  attaches  —  but  see  the  — S  option  for  how  this  field  is  modified, 

pi  pages  paged  in 

po  pages  paged  out 

fr  pages  freed  per  second 

de  anticipated  short  term  memory  shortfall 

sr  pages  scanned  by  clock  algorithm,  per-second 

disk  Reports  number  of  disk  operations  per  second  (this  field  is  system  dependent).  For  Sun 
systems,  four  slots  are  available  for  up  to  four  drives:  “xO”  (or  “sO”  for  SCSI  disks), 
“xF’,  *‘x2’\  and  “x3”. 

faults  Reports  trap/interrupt  rate  averages  per  second  over  last  5  seconds, 
in  (non  clock)  device  interrupts  per  second 
sy  system  calls  per  second 

cs  cpu  context  switch  rate  (switches/sec) 
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VMSTAT(8) 


cpu  Gives  a  breakdown  of  percentage  usage  of  CPU  time. 

us  user  time  for  normal  and  low  priority  processes 

sy  system  time 

id  cpu  idle 

OPTIONS 

— f  Report  on  the  number  of  forks  and  vforks  since  system  startup  and  the  number  of  pages 

of  virtual  memory  involved  in  each  kind  of  fork. 

Display  the  contents  of  the  sum  structure,  giving  the  total  number  of  several  kinds  of 
paging-related  events  which  have  occurred  since  boot. 

— S  Report  on  swapping  rather  than  paging  activity.  This  option  will  change  two  fields  In 

vmstat's  “paging’*  display:  rather  than  the  “re”  and  “at”  fields,  vmstat  will  report  “si” 
(swap-ins),  and  “so”  (swap-outs). 

FILES 

/dev/kmem 

/vmunix 
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NAME 

ypinit  -  build  and  install  yellow  pages  database 

SYNOPSIS 

ypinit  — m 

ypinit  —8  master_name 
DESCRIPTION 

Ypinit  sets  up  a  yellow  pages  (YP)  server’s  database.  It  can  be  used  to  set  up  a  master  server  or 
a  slave  server.  You  must  be  the  superuser  to  run  it.  It  asks  a  few  questions,  which  are  self- 
explanatory,  and  reports  success  or  failure  to  the  terminal. 

It  sets  up  a  master  server  using  the  simple  model  in  which  that  server  is  master  to  all  maps  in 
the  data  base.  This  is  the  way  to  bootstrap  the  YP  system;  later  if  you  want  you  can  change  the 
association  of  maps  to  masters  by  changing  the  information  in  the  YP  map  named  ypmaps.  All 
databases  are  built  from  scratch,  either  from  information  available  to  the  program  at  runtime,  or 
from  the  ASCII  data  base  files  in  fete.  The  list  of  which  files  will  be  used  to  generate  the  data¬ 
bases  is  below  in  the  FILES  section.  All  of  these  files  should  be  in  their  traditional  form,  rather 
than  the  abbreviated  form  used  on  client  machines,  which  primarily  use  the  YP  services  to  access 
the  same  information. 

A  slave  YP  server  database  is  set  up  by  copying  an  existing  database  from  a  running  server.  The 
ma$ter_name  argument  should  be  the  host  name  of  YP  server,  which  is  either  actually  the  mas¬ 
ter  server  for  all  the  maps,  or  a  server  the  data  base  of  which  is  believed  to  be  up-to-date  and 
stable.  If  your  network  uses  different  server  machines  acting  as  the  master  of  different  maps,  of 
course  no  single  machine  will  be  the  master  of  all  maps.  This  doesn’t  matter;  the  yp  data  bases 
will  converge  automatically  in  time,  and  the  process  can  be  sped  up  somewhat  by  using  yppush{S) 
and  yppull{8y  Just  choose  a  YP  server  which  is  up,  reachable,  and  stable. 

OPTIONS 

—m  Indicates  that  the  local  host  is  to  be  the  YP  master. 

—8  Set  up  a  slave  database. 

FILES 

/etc/passwd 

/etc/group 

/etc/hosts 

/etc/networks 

/etc/services 

/etc/protocols 

/etc/netgroup 

SEE  ALSO 

makedbm(8),  ypfiles(8),  yppush(8),  ypmake(8) 
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NAME 

ypmake  —  rebuild  yellow  pages  database 

SYNOPSIS 

cd  /ete/yp  ;  make 

DESCRIPTION 

There  is  a  Makefile  in  /ete/yp  for  building  the  yellow  pages  database.  With  no  arguments,  make 
creates  dbm  databases  for  everything  that  is  out  of  date,  and  then  executes  yppusA(8)  to  notify 
slave  databases  that  there  has  been  a  change. 

Typing  make  passwd  will  create  and  yppueh  just  the  password  database  (assuming  it  is  out  of 
date).  Likewise,  moJbe  hoate  and  make  networks  will  create  and  yppush  the  host  and  network 
files,  /etc/kosts  and  / etc/ networks . 

There  are  three  special  variables:  DIR,  which  gives  the  directory  of  the  source  files;  NOPUSH, 
which  when  non-null  inhibits  doing  a  yppush  of  the  new  database  files;  and  DOM,  used  to  con¬ 
struct  a  domain  other  than  the  master’s  default  domain.  The  default  for  DIR  is  / etc,  and  the 
default  for  NOPUSH  is  the  null  string. 

SEE  ALSO 

makedbm(8),  ypserv(8) 
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NAME 

yppasswdd  —  server  for  modifying  yellow  pages  password  file 
SYNOPSIS 

/u8r/ete/rpc«ypp&sftwdd  file  [  — m  argl  arg2  ) 

DESCRIPTION 

Yppasswdd  is  a  server  that  handles  password  change  requests  from  yppa88wd{iy  It  changes  a 
password  entry  in  file,  which  is  assumed  to  be  in  the  format  of  passu;rf(5).  An  entry  in  file  will 
only  be  changed  if  the  password  presented  by  yppa88wd{l)  matches  the  encrypted  password  of 
that  entry. 

If  the  — m  option  is  given,  then  after  file  is  modified,  a  make{l)  will  be  performed  in  fetc/yp. 
Any  arguments  following  the  flag  will  be  passed  to  make. 

This  server  is  not  run  by  default,  nor  can  it  be  started  up  from  inetd{S).  If  it  is  desired  to  enable 
remote  password  updating  for  the  yellow  pages,  then  an  entry  for  should  be  put  in  the 

/ etc/rc  file  of  the  host  serving  as  the  master  for  the  yellow  pages  pasewd  file. 

EXAMPLE 

If  the  yellow  pages  password  file  is  stored  as  /etcfyp/src/pasewd,  then  fo  have  password  changes 
propagated  immediately,  the  server  should  be  invoked  as 

/usr/etc/rpc.yppasswdd  /etc/yp/src/passwd  -m  passwd  DIR=/etc/yp/src 

FILES 

/etc/yp/Makefile 
SEE  ALSO 

yppasswd(l),  passwd(5),  ypfiles(5),  ypmake(8) 

CAVEAT 

This  server  will  eventually  be  replaced  with  a  more  general  service  for  modifying  any  map  in  the 
yellow  pages 
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NAME 

yppush,  yppull,  yppoll  -  yellow  pages  administration  utilities 
SYNOPSIS 

yppush  I  — h  hostname  ]  |  — d  domainname  |  mapname 
yppull  I  — h  hostname  ]  |  — d  domainname  ]  mapname 
yppoll  [  — h  hostname  |  |  — d  domainname  ]  mapname 

DESCRIPTION 

These  commands  supply  an  interface  to  the  running  yellow  pages  (YP)  system.  They  make  use  of 
YP  services  themselves,  which  must  be  available  at  the  site  where  the  commands  are  issued.  The 
issuing  site  may  be  a  yp  client;  it  need  not  be  a  server.  The  rpcm/o(8)  program  may  be  useful  for 
determining  if  the  YP  processes  ypserv  and  yphind  are  up  and  running  at  a  site.  The  processes 
that  comprise  the  YP  system  are  described  in  jfpscrti(8).  The  YP  database  format  is  described  in 
ypfiles{S). 

Yppush  tells  a  master  YP  server  process  (ypaerv)  to  direct  its  peer  processes  to  set  the  master  of 
the  named  map  to  that  master  server,  and  to  get  a  new  copy  of  the  named  map.  If  the  host  is 
not  the  master  of  the  named  map,  the  command  will  succeed,  but  no  action  will  be  taken  by  the 
YP  server. 

Yppull  tells  a  slave  YP  server  process  (ypserw)  to  try  and  get  a  more  recent  copy  of  the  named 
map,  preferably  from  the  map’s  master.  If  the  server  is  the  master  of  the  named  map,  the  com¬ 
mand  will  succeed,  but  no  action  will  be  taken  by  the  YP  server. 

Yppoll  asks  a  ypserv  (master  or  slave)  for  information  about  one  map.  The  information  returned 
is  whether  the  map  exists  at  the  site,  what  version  number  is  in  the  map,  and  which  server  is 
thought  to  be  the  map’s  master. 

OPTIONS 

— h  Specifies  the  hostname  on  which  the  ypserv  process  is  running.  The  default  is  the  local 

host. 

— d  Specifies  an  alternate  domainname  for  the  YP.  The  default  is  the  domain  for  the  local 

host. 

SEE  ALSO 

rpcinfo(8),  ypserv(8),  ypfiles(5) 
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NAME 

ypserv  —  yellow  pages  server  and  binder  processes 

SYNOPSIS 

/etc/ypserv 

/ctc/ypblnd 

DESCRIPTION 

The  yellow  pages  (YP)  provides  a  simple  network  lookup  service.  YP  consists  of  databases  and 
processes.  The  databases  are  rfim(3)  files  in  a  directory  tree  rooted  at  ftic/yp^  described  In 
ypjHe8{b).  The  processes  are  jeicj ypserv,  the  YP  database  server,  and  letcfyphind,  the  YP 
binder.  The  programmatic  interface  to  YP  is  described  in  ypc/n^(3N).  Administrative  tools  are 
described  in  yppush{S)  and  ypc(2;(l).  Database  generation  and  maintenance  tools  are  described  in 
ypzni7(8),  ypmake{S),  and  makedbm{8). 

Both  ypserv  and  ypbind  are  daemons:  they  are  typically  activated  at  system  startup  time  from 
/ etcIrcAocal,  and  theoretically  run  forever.  Ypserv  runs  only  on  YP  server  machines  with  a 
complete  YP  database.  Ypbind  runs  on  all  machines  using  YP  services,  both  YP  client  machines 
and  YP  servers. 

The  ypserv  daemon  has  two  functions:  to  look  up  information  in  its  local  database  (or  YP  maps), 
and  to  keep  that  database  consistent  with  those  of  its  peers. 

The  operations  performed  by  pp^ert;  are  defined  in  the  header  file  <rpC8Vcfyp_prot.h>,  Com¬ 
munication  to  and  from  ypserv  is  by  means  of  RPC  calls.  Lookup  functions  are  supplied  (as  a  C 
library)  in  the  ypclnt  package,  defined  in  the  header  file  <rpc8vc/ypclnt.h>  and  described  in 
ppc/n^(3N).  There  are  three  types  of  functions:  match,  get  first,  and  get  next.  The  match  opera¬ 
tion  takes  a  key,  and  returns  the  associated  value  within  a  named  map  and  domain.  (Domains 
are  described  in  ypfiles  (8).)  The  get  first  operation  returns  the  first  key-value  pair  within  a 
named  map  and  domain,  and  get  next  can  be  used  to  enumerate  the  remainder.  There  are  other 
operations  performed  by  ypserv:  they  either  give  back  information  internal  to  the  process  itself, 
or  are  useful  in  speeding  up  the  update  propagation  algorithm  which  is  discussed  in  the  next 
paragraph.  Non-lookup  functions  are  accessible  to  programmers  by  coding  the  RPC  calls  defined 
in  <rpcsvcf  yp_prot,h> ,  and  at  the  shell  level  by  using  the  tools  yppush,  yppull,  and  yppoll,  all 
described  in  yppnsh{S). 

This  paragraph  discusses  how  map  updates  propagate  among  YP  servers,  and  how  propagation 
converges.  Each  map  is  associated  with  a  version  (or  order)  number.  Each  ypserv  process  com¬ 
municates  with  its  peers,  and  tries  to  find  the  map  availible  with  the  greatest  order  number.  The 
order  number  is  set  at  the  time  the  map  is  is  generated.  Each  map  is  associated  with  a  dis¬ 
tinguished  YP  server  host,  called  the  map's  master.  Updates  to  that  map  should  be  done  only  at 
the  map’s  master  —  maps  should  be  generated  only  on  their  master  host.  As  each  ypserv  tries  to 
find  the  version  of  any  map  containg  the  greatest  order  number,  it  first  tries  to  communicate 
with  the  map’s  master.  If  the  master  is  unreachable,  it  chooses  another  peer  at  random,  and  will 
transfer  that  map  from  any  peer  that  has  a  map  containing  an  order  number  greater  than  the 
one  in  the  map  it  currently  has. 

This  paragraph  discusses  the  ypbind  process,  whose  function  is  to  remember  information  that  lets 
clients  on  a  single  node  communicate  with  ypserv  processes.  Ypbind  must  be  running  on  every 
network  node;  ypserv  may  or  may  not  be  running  on  the  same  node,  but  must  be  running  some¬ 
where  on  the  network.  The  information  ypbind  remembers  is  called  a  binding  —  the  association 
of  a  domain  name  with  the  internet  address  of  the  YP  server,  and  the, port  on  that  host  at  which 
the  ypserv  process  is  listening  for  service  requests.  The  process  of  binding  is  driven  by  client 
requests.  As  a  request  for  an  unbound  domain  comes  in,  the  ypbind  process  broadcasts  on  the 
net  trying  to  find  a  ypserv  process  that  claims  to  serve  maps  within  that  domain.  Since  binding 
is  accomplished  by  broadcasting,  there  must  be  at  least  one  ypserv  process  on  every  net.  Once  a 
domain  is  bound  by  a  particular  ypbind,  that  same  binding  is  given  to  every  client  process  on  the 
node  running  that  ypbind.  The  binding  is  verified  before  it  is  given  out  to  a  client  process.  If 
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ypbind  is  unable  to  speak  to  the  ypserv  process  using  its  binding  it  marks  the  domain  as  unbound, 
tells  the  client  process  that  the  domain  is  unbound,  and  tries  again  to  bind  the  domain.  Requests 
for  binding  received  by  an  unbound  domain  will  fail  immediately. 

SEE  ALSO 

ypclnt(3N),  ypfiles(5),  makedbm(8),  ypcat(8),  ypinit(8),  ypmake(8),  yppush(8) 


o 
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NAME 

ypwhich  —  which  machines  are  the  YP  server  and  master? 
SYNOPSIS 


ypwhich  [  — d  domainname  ]  [  hostname  ] 
ypwhich  [  — d  domainname  ]  [  |  — m  [  mname  [ 


DESCRIPTION 

Ypwhich  tells  which  YP  server  supplies  yellow  pages  to  a  YP  client,  and  which  YP  server  is  the 
master  for  a  map.  If  invoked  without  arguments,  it  gives  the  YP  server  for  the  local  machine.  If 
hostname  is  specified,  that  machine  is  queried  to  find  out  which  YP  master  it  is  using. 


If  the  — m  switch  is  used  without  mname,  a  list  of  every  map  in  the  domain  and  the  master  of 
each  will  be  printed-  If  mname  is  specified,  only  the  master  YP  server  for  that  map  is  printed. 
Mname  may  be  a  mapname,  or  a  nickname  for  a  mapname.  Mapnames  and  nicknames  are 
described  in  ypcat{^). 


OPTIONS 

— d  Domainname  specifies  the  name  of  a  YP  domain.  The  default  is  the  default  domain  for 

the  local  machine. 

— m  Find  the  master  YP  server  for  a  map,  or  for  all  maps  in  a  domain.  No  hostname  may  be 

specified  with  — m. 

—t  Inhibit  nickname  translation;  useful  if  there  is  a  mapname  identical  to  a  nickname.  This 
is  not  true  of  any  Sun-supplied  map. 

SEE  ALSO 

ypfiles(5),  rpcinfo(8),  yppush(8),  ypserv(8) 
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Special  Characters 

%job  £  —  job  to  background  —  csh,  72 
%Job  —  job  to  foreground  —  csh,  72 
.  shell  command  —  sh,  292 
;  shell  command  —  sh,  292 
O  —  arithmetic  on  shell  variables  —  csh,  72 

A 

abort  printer  —  Ipc,  626 
ac  —  login  accounting,  478 
login  accounting  —  ac,  478 
accounting  on  or  off,  583 
accton  —  accounting  on  or  off,  583 
adb  —  debugger,  2 
adb  scripts  —  adbgen,  479 
adbgen  —  generate  adb  script,  479 
addbib  —  create  bibliography,  9 
address  resolution  display  and  control  —  arp, 
484 

adduser  —  add  new  user  account,  481 
ad  jacentscreer^s,  11 
admin  —  adminster  SCCS,  12 
administration 

install  —  install  files,  176 
adventure  —  exploration  game,  409 
alias  —  shell  macros  —  csh,  66 
alias  substitution 
in  C-Shell,  61 

alloc  —  show  memory  use  —  csh,  66 
allow  messages  —  mesg,  212 
alter  process  priority  —  renice,  563 
analyze  —  crash  analyzer,  483 
ar  —  library  maintenance,  16 


archive 

ar  —  library  maintenance,  16 
archive  tapes  —  tar,  333 
archives 
copy,  55 

cpio  —  copy  archives,  55 
argument  list  processing 
in  C-Shell,  75  thru  76 

arithmetic  —  drill  in  number  facts,  410 
arp  —  address  resolution  display  and  control, 
484 

as  —  assembler,  18 
ASCII  dump  file  —  od,  224 
ascii  —  ASCII  character  set,  468 
at  —  do  job  at  specified  time,  19 
autoboot  procedures  —  reboot,  561 
awk  —  scan  and  process  patterns,  20 

B 

backgammon  —  backgammon  game,  411 
backspace  magnetic  tape  files  —  mt,  218 
backspace  magnetic  tape  records  —  mt,  218 
backup  dumps  —  dump,  503 
banner  —  large  banner,  413 
basename  —  strip  filename  affixes,  23 
bballs  —  black  and  white  demo,  415 
bbounce  —  black  and  white  demo,  415 
be  —  calculator  language,  24 
bed  —  convert  to  antique  media,  414 
bdemos  —  black  and  white  demo,  415 
bdraw  —  interactive  graphics  drawing,  426 
bg  —  job  to  background  —  csh,  66 
bibliographic  references 


bibliographic  references,  continued 

refer  —  insert  literature  references,  267 
bibliography  management 
create  or  extend,  9 

indxbib  —  make  inverted  index,  173 
lookbib  —  find  bibliographic  references, 
188 

sortbib  —  sort  bibliographic  database, 
305 

biff  —  mail  notifier,  26 
binary  file  transmission 

uudecode  —  decode  binary  file,  370 
uuencode  —  encode  binary  file,  370 
binmail  —  version  7  mail,  27 
biod  —  NFS  daemon,  549 
bjunp  —  black  and  white  demo,  415 
black  and  white  demos 
bbounce,  415 
bdemos,  415 
bjun^,  415 
bphoto,  415 
brotcube,  415 
blocks 

count,  in  file  —  sum,  315 
boggle  —  boggle  game,  416 
bootstrap  procedures  —  reboot,  561 
bootstrap  PROM  monitor  program,  536 
Bourne  Shell  —  sh,  292 
:,  296 

break,  296 
case,  292 
cd,  296 

continue,  296 
eval,  296 
exec,  296 
exit,  296 
export,  296 
false  command,  132 
for, 292 
if,  292 
login,  296 
newgrp,  296 
read,  296 
readonly,  296 
set,  296 
shift,  297 
times,  297 
trap,  297 
umask,  297 
wait,  297 
while,  293 

bphoto  —  black  and  white  demo,  415 
break  shell  command  —  sh,  296 
break  —  exit  loop  —  csh,  66 
breaksw  —  exit  switch  —  csh,  66 
broadcast  messages 

rwall  —  to  all  users  on  network,  277,  391 


brotcube  —  black  and  white  demo,  415 
bsuncube  —  display  3-D  Sun  logo,  417 
make  random  library  —  ran  lib,  258 
build  system  configuration  files  —  con  fig,  489 
build  yellow  pages  database  —  ypinit,  611 

c 

C  compiler,  33 
C language 

indent  —  format  C  source,  170 
C  programming  language 

ctags  —  create  tags  file,  78 
mkstr  —  create  C  error  messages,  214 
tcov  —  code  coverage  tool,  338 
vgrind  —  make  formatted  C  listings,  377 
xstr  —  extract  strings  from  C  code,  403 
C  programming  languages 

lint  —  C  program  verifier,  183,  183 
C  Shell  variables,  72  thru  75 
argv,  72 
cdpath,  73 
cwd,  73 
echo,  73 
histchars,  73 
history,  73 
home,  73 
ignoreeof,  73 
mail,  73 
noclobber,  73 
noglob,  73 
nonomatch,  73 
notify,  73 
path,  73 
prompt,  74 
savehist, 74 
shell,  74 
status,  74 
time,  74 
verbose,  75 
C-Shell  commands 

%job  —  job  to  foreground,  72 
%job  &  —  job  to  background,  72 
@  —  arithmetic  on  shell  variables,  72 
alias  —  shell  macros,  66 
alloc  —  show  memory  use,  66 
bg  —  job  to  background,  66 
break  —  exit  loop,  66 
breaksw  —  exit  switch,  66 
case  —  selector  in  switch,  66 
cd  —  change  directory,  66 
chdir  —  change  directory,  66 
continue  —  cycle  loop,  67 
default  —  catchall  in  switch,  67 
echo  —  echo  arguments,  67 
else  —  alternative  commands,  67 
end  —  end  loop,  67 
endif  —  end  conditional,  67 
endsw  —  end  switch,  67 


C-Shell  commands,  continued 

eval  —  re-evaluate  shell  data,  67 
exec  —  execute  command,  67 
exit  —  exit  shell,  67 
fg  —  job  to  foreground,  67 
for  each  —  loop  on  list  of  names,  67 
glob  —  filename  expand  argument  list,  67 
goto  —  command  transfer,  68 
hashstat  —  display  hashing  statistics,  68 
history  —  display  history  list,  68 
if  —  conditional  statement,  68 
jobs  —  display  job  list,  68 
kill  —  kill  jobs  and  processes,  68 
limit  —  alter  resource  limitations,  69 
login  —  login  new  user,  69 
logout  —  end  session,  69 
nice  —  run  low  priority  process,  69 
nohup  —  run  command  immune  to  hang¬ 
ups,  69 

notify  —  request  immediate  notification, 

69 

onintr  —  handle  interrupts  in  scripts,  69 
popd  —  pop  shell  directory  stack,  70 
pushd  —  push  shell  directory  stack,  70 
rehash  —  recompute  command  hash  table, 

70 

repeat  —  execute  command  repeatedly,  70 
set  —  change  value  of  shell  variable,  70 
setenv  —  set  variable  in  environment,  70 
shift  —  shift  argument  list,  70 
source  —  read  commands  from  file,  71 
stop  —  halt  job  or  process,  71 
suspend  —  suspend  shell,  71 
switch  —  multi-way  branch,  71 
time  —  time  command,  71 
umask  —  change/display  file  creation  mask, 

71 

unalias  —  remove  aliases,  71 
unhash  —  discard  hash  table,  71 
unlimit  —  remove  resource  limitiations, 
71 

unset  —  discard  shell  variables,  72 
unsetenv  —  remove  environment  vari¬ 
ables,  72 

wait  —  wait  for  background  process,  72 
while  —  repeat  commands,  72 
cal  —  display  calendar,  29 
calculator,  95 

calendar  —  reminder  service,  30 
call  graph 

display  profile  data,  153 
Canfield  —  Canfield  solitaire  card  game,  418 
case  shell  command  —  sh,  292 
case  —  selector  in  switch  —  csh,  66 
cat  —  concatenate  files,  31 
catman  —  create  cat  files  for  manual,  485 
cb  —  C  beautifier,  32 
cballs  —  color  demo,  423 


cc  —  C  compiler,  33 
ccat  —  compress  files,  53 
cd  —  change  directory,  36 
cd  shell  command  —  sh,  296 
cd  —  change  directory  —  csh,  66 
cdc  —  change  delta  commentary,  37 
cdraw  —  color  demo,  423,  426 
change 

default  shell,  43 
delta  commentary,  37 
directory,  36 
group,  41 
login  shell,  43 
mode  of  file,  42 
permissions  of  file,  42 
working  directory,  36 
change  login  password  —  passwd,  227 
change  name  of  directory  —  mv,  219 
change  name  of  file  —  mv,  219 
change  priority  of  command  —  nice,  220 
change  process  priority  —  renice,  563 
character  translation  —  tr,  352 
characters  for  equations  —  eqnchar,  459 
characters  in  file 

count  —  wc,  392 
chase  —  escape  killer  robots,  419 
chdir  —  change  directory  —  csh,  66 
check  directory  —  dcheck,  497 
check  file  system  —  fsck,  508 
check  spelling —  spell,  306 
checkeq  —  check  eqn  constructs,  119 
checknews  —  check  for  news,  39 
checknr  —  check  nrofT/troff  files,  40 
chess  —  chess  game,  420 
chesstool  —  chess  game,  421 
chgrp  —  change  group,  41 
chlng  —  book  of  changes,  422 
chmod  —  change  mode,  42 
chown  —  change  owner  of  file,  486 
chsh  —  change  shell,  43 
clean  print  queue  —  Ipc,  526 
clean  UUCP  spool  area  —  uuclean,  606 
clear  —  clear  screen,  44 
clear  i-node  —  clri,  487 
clocktool  —  display  time  in  window,  46 
clri  —  clear  i-node,  487 
cmp  —  compare  files,  47 
code  coverage  tool  —  tcov,  338 
code  formatter 

indent  —  format  C  source,  170 
col  —  filter  reverse  paper  motions,  48 
colcrt  —  document  previwer,  49 
color  demo 

cballs,  423 
cdraw,  423 
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color  demo,  continued 
cphoto,  423 
cpipes,  423 
cshowmap,  423 
csnow,  423 
csuncubo,  423 
csunlogo,  423 
cvlsi,  423 

colrm  —  remove  columns  from  file,  50 
columns 

print  in  multiple  —  pr,  239 
remove  from  file,  50 
coxnb  —  combine  deltas,  61 
combine  SCCS  deltas,  51 
comm  —  find  commonality,  52 
command 

change  priority  of  —  nice,  220 
describe  —  whatis,  394 
locate  —  whereis,  395 
run  immune  to  hangup  —  nohup,  220 
command  execution 
in  C-Shell,  75 
command  interpreter 

sh  —  Bourne  Shell,  292 
command  substitution 
in  C-Shell,  63 
commands 

introduction,  1 
communications 

cu  —  connect  to  remote  system,  346 
enroll  —  enroll  for  secret  mail,  402 
mail  —  send  and  receive  mail,  200 
permit  or  deny  messages  —  mesg,  212 
talk  —  talk  to  another  user,  332 
telnet  —  TELNET  interface,  342 
tip  —  connect  to  remote  system,  346 
uuclean  —  clean  UUCP  spool  area,  606 
UUCP  —  UNIX  to  UNIX  copy,  368 
uudecode  —  decode  binary  file,  370 
uuencode  —  encode  binary  file,  370 
uulog  —  UUCP  log,  368 
uusend  —  send  file  to  remote  host,  371 
xx\xx  —  UNIX  to  UNIX  command  execution, 
372 

write  —  write  to  another  user,  400 
xget  —  receive  secret  mail,  402 
xsend  —  send  secret  mail,  402 
compare 
files,  47 

files  differentially,  105 
three-way  differential,  107 
compare  versions  of  SCCS  file  —  sccsdiff, 
284 

compile  Pascal  programs  —  pc,  228 
compiler  generator,  128,  404 
compiler  generators 

lex  —  generate  lexical  analyzer,  182 


compilers 

cc  —  C  compiler,  33 
conipress  —  compress  files,  53 
compress  files,  63 
comsat  —  biff  server,  488 
concatenate  files 

cat  —  concatenate  files,  31 
con  fig  —  build  system  configuration  files,  489 
configuration  files 

build  —  con  fig,  489 

configure  network  interface  parameters  — 
ifconfig,  519 

connect  to  remote  system  —  cu,  346 
connect  to  remote  system  —  tip,  346 
continue  shell  command  —  sh,  296 
continue  —  cycle  loop  —  csh,  67 
control  line  printer  —  Ipc,  526  thru  527 
control  magnetic  tape  —  mt,  218 
convert 

spaces  to  tabs,  125 
tabs  to  spaces,  125 
convert  and  copy  files,  97 
convert  foreign  font  files  —  vswap,  386 
convert  units  —  units,  365 
copy 

archives,  55 
files,  54 

copy  files  from  remote  machine  —  rep,  261 
copy  standard  output  to  many  files  —  tee,  339 
core  images 

get  of  process,  147 
count  blocks  in  file  —  sum,  315 
count  lines,  words,  characters  in  file  —  wc,  392 
cp  —  copy  files,  64 
cphoto  —  color  demo,  423 
cpio  —  copy  archives,  55 
cpipes  —  color  demo,  423 
CPU  PROM  monitor  program,  536 
crash  analyzer  —  analyze,  483 
crash  —  crash  procedure,  494 
create 

bibliography,  9 
delta,  99 

sees  data  bases,  12 
SCCS  delta,  99 
tags  file,  78 

create  cat  files  for  manual  —  catman,  485 
create  directory  —  mkdir,  213 
create  error  log  —  dmesg,  502 
create  file  system  —  xnkfs,  633 
create  font  width  table  —  width,  388 
create  mail  aliases  database  —  newaliases, 
547 

create  new  file  system  —  newfs,  548 
create  permuted  index  —  ptx,  252 
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create  prototype  file  system  —  mkproto,  535 

make  random  library  —  ranlib,  258 

create  script  of  terminal  session  —  script,  288 

create  special  file  —  mknod,  534 

create  system  configuration  files  —  con  fig,  489 

create  system  log  entry  —  syslog,  330 

create  yellow  pages  database  —  ypinit,  611 

create  yellow  pages  dbm  file  —  makedbm,  530 

cribbage  —  cribbage  card  game,  424 

cron  —  clock  daemon,  496 

cross  reference  Pascal  program  —  pxref,  257 

crypt  —  encrypt,  57 

csh  —  C  shell,  58  thru  77 

cshowmap  —  color  demo,  423 

csnow  —  color  demo,  423 

csuncube  —  color  demo,  423 

csunlogo  —  color  demo,  423 

ctags  —  create  tags  file,  78 

cu  —  connect  to  remote  system,  346 

current  domain 

set  or  display,  108 
curve  fitting 

spline  —  interpolate  smooth  curve,  307 
cvlsi  —  color  demo,  423 

D 

DARPA  Internet  directory  service  —  whois, 
399 

DARPA  TELNET  protocol  server  —  telnetd, 
600 

DARPA  Time  server  —  timed,  602 

DARPA  to  RPC  mapper  —  portmap,  553 

Data  Encryption  Standard,  102 

database  operator  —  join,  177 

date  —  date  and  time,  79 

dbx  —  debugger,  80 

dbxtool  —  debugger,  90 

dc  —  desk  calculator,  95 

dcheck  —  directory  consistency  check,  497 

dd  —  convert  and  copy,  97 

debug  network  —  ping,  552 

debug  tools 

adb  —  debugger,  2 
adbgen  —  generate  adb  script,  479 
dbx  —  debugger,  80 
dbxtool  —  debugger,  90 
decimal  dump  file  —  od,  224 
decode  binary  file  —  uudecode,  370 
decode  files,  57 
crypt  —  decrypt,  57,  102 
decrypt  files,  57 

default  —  catchall  in  switch  —  csh,  67 
delete 

columns  from  file,  50 
filename  affixes,  23 


delete,  continued 

nroff,  troff,  tbl  and  eqn  constructs,  101 
delete  directory  —  rmdir,  273 
delete  outdated  news  articles  —  expire,  506 
delete  print  jobs  —  Iprm,  194 
delete  repeated  lines  —  uniq,  364 
delta 

change  commentary,  37 
combine,  51 
remove  —  rmdel,  272 
delta  —  make  delta,  99 
demount  file  system  —  umount,  539 
deny  messages  —  mesg,  212 
derof  f  —  remove  troff  constructs,  101 
des  —  data  encryption,  102 
describe  command  —  what  is,  394 
desk  calculator,  95 
df  —  display  free  space,  104 
diag  —  initialize/diagnose  disk,  498 
diagnose/initialize  disk  —  diag,  498 
diagnostics 

gxtest  —  graphics  board  diagnostics,  515 
imemtest  —  memory  diagnostic,  520 
diagnostics  —  sysdiag,  596 
dif  f  —  differential  compare,  105 
dif  f3  —  three-way  differentia!  compare,  107 
directory 

change  name  of  —  mv,  219 
change  working,  36 
check  consistency  —  dcheck,  497 
delete  —  rm,  271 
delete  —  rmdir,  273 
differential  compare,  105 
display  name  of  working  —  pwd,  253 
erase  —  rm,  271 
erase  —  rmdir,  273 
list  contents  of  —  Is,  196 
make  —  mkdir,  213,  214 
move  —  mv,  219 
purge  —  rm,  271 
purge  —  rmdir,  273 
remove  —  rm,  271 
remove  —  rmdir,  273 
rename  —  mv,  219 
disable  print  queue  —  Ipc,  526 
disk 

dkinfo  —  geometry  information,  501 
disk  diagnose/initialize  —  diag,  498 
disk  diagnostics  —  sysdiag,  596 
display 

call  graph  profile  data,  153 
current  domain,  108 
current  host  identifier,  165 
current  host  name,  166 
date,  79 

date  and  time,  79 
disk  usage,  109 
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display,  continued 

first  lines  of  file,  163 
free  space  in  file  system,  104 
group  membership,  162 
identifier  of  current  host,  165 
name  of  current  host,  166 
time  and  date,  70 
time  in  window,  46 
display  editor  —  vi,  379 
display  effective  user  name  —  whoami,  398 
display  file  names  —  Is,  196 
display  last  commands  —  lastconan,  180 
display  last  part  of  file  —  tail,  331 
display  name  list  —  nm,  221 
display  online  manuals  —  man,  211 
display  page  size  —  pagesizo,  226 
display  printer  queue  —  Ipq,  190 
display  process  status  —  ps,  247 
display  program  profile  —  prof,  242 
display  SCCS  file  editing  status  —  sact,  279 
display  status  of  local  hosts  —  ruptime,  276 
display  system  up  time  —  uptime,  366 
display  users  on  system  —  users,  367 
display  waiting  mail  —  prmail,  241 
display  working  directory  name  —  pwd,  253 
dkinfo  —  disk  geometry  information,  601 
dmesg  —  create  error  log,  502 
document  preparation 

bibliography  management,  9 
document  production 

checknr  —  check  nroff/troff  files,  40 
col  —  filter  reverse  paper  motions,  48 
colcrt  command,  49 

delete  nroff,  troff,  tbl  and  eqn  constructs, 
101 

eqnchar  —  special  characters  for  equa- 
tions,  459 

equation  processor,  119 
indxbib  —  make  inverted  index,  173 
lookbib  —  find  bibliographic  references, 
188 

man  —  macros  to  format  manual  pages,  467 
mathematical  formatting,  119 
mo  —  macro  package,  469 
ins  —  macro  package,  471 
nroff  —  document  formatter,  222 
ptx  —  generate  permuted  index,  252 
refer  —  insert  literature  references,  267 
remove  nroff,  troff,  tbl  and  eqn  constructs, 
101 

set  equations,  119 
simple  formatter,  136 

soolim  —  eliminate  .so’s  from  nroff  input, 
302 

sortbib  —  sort  bibliographic  database, 
305 

spell  —  check  spelling,  306 


document  production,  continued 
tbl  —  table  formatter,  337 
troff  —  typeset  documents,  353 
vfontinfo  —  examine  font  files,  376 
vtroff  —  format  document  for  raster 
printer,  387 

width  —  make  font  width  table,  388 
domain 

set  or  display  current,  108 
domainname  —  set/display  domain  name,  108 
draw  graph,  157 
du  —  display  disk  usage,  109 
dun^?  —  dump  file  system,  503 
dump  frame  buffer  image  —  screenduuiqp,  285 
dumpfs  —  dump  file  system  information,  505 

E 

echo  —  echo  arguments,  110 
echo  —  echo  arguments  —  csh,  67 
ed  —  line  editor,  111 
edit 

fonts,  138 

edit  —  line  editor,  123 
edit  password  file  —  vipw,  608 
editing  text 

edit  —  line  editor,  123 
ex  —  line  editor,  123 
sed  —  stream  editor,  289 
editing  text  files 

ed  —  line  editor,  111 
editor 

icon,  167 

egrep  —  pattern  scanner,  159 

eliminate  .so’s  from  nroff  input  —  soelim,  302 

else  —  alternative  commands  —  csh,  67 

emulate  Tektronix  4014  —  tektool,  340 

enable  print  queue  —  Ipc,  526 

encode  binary  file  —  uuencodo,  370 

encode  files,  57 

encrypt,  102 

encrypt  files,  57 

encrypted  mail 

enroll  for  —  enroll,  402 
receive  —  enroll,  402 
send  —  xsend,  402 
encryption  key 

generate  —  makekey,  532 
end  —  end  loop  —  csh,  67 
endif  —  end  conditional  —  csh,  67 
endsw  —  end  switch  —  csh,  67 
enroll  —  enroll  for  secret  mail,  402 
environment 

display  variables  —  prlntenv,  240 
tset  —  set  terminal  characteristics  for,  356 
environment  variables 
in  C-Shell,  72  thru  75 
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eqn 

remove  constructs,  101 
eqn  —  mathematical  typesetting,  119 
eqnchar  —  special  characters  for  equations,  459 
erase  directory  —  rmdir,  273 
erase  file  or  directory  —  rm,  271 
erase  magnetic  tape  —  mt,  218 
error  —  analyze  error  messages,  121 
eval  shell  command  —  sh,  296 
eval  —  re-evaluate  shell  data  —  csh,  67 
evaluate  expressions,  126 
ex  —  line  editor,  123 
exec  shell  command  —  sh,  296 
exec  —  execute  command  —  csh,  67 
execute  commands  at  specified  times  —  cron, 
496 

executing  non-builtin  commands 
in  C-Shell,  75 

exit  shell  command  —  sh,  296 

exit  —  exit  shell  —  csh,  67 

expand  —  expand  tabs,  125 

expire  —  remove  outdated  news  articles,  506 

export  shell  command  —  sh,  296 

expr  —  evaluate  expressions,  126 

expression  evaluation,  126 

extend 

bibliography,  9 

extract  strings  from  C  code  —  xstr,  403 
eyacc  —  compiler  generator,  128 

F 

f77  —  FORTRAN  compiler,  129 
fastboot  —  reboot  system,  507 
fasthalt  —  halt  system,  507 
fg  —  job  to  foreground  —  csh,  67 
fgrep  —  pattern  scanner,  159 
file  . 

browse  through  text —  more,  215 

browse  through  text —  page,  215 

change  name  of  —  mv,  219 

change  ownership  —  chown,  486 

copy  from  remote  machine  —  rep,  261 

count  lines,  words,  characters  in  —  wc,  392 

delete  —  rm,  271 

display  last  part  of  —  tail,  331 

dump  —  od,  224 

erase  —  rm,  271 

find  lines  in  sorted  —  look,  187 

identify  version  —  what,  393 

move  —  mv,  219 

print  —  Ipr,  192 

purge  —  rm,  271 

remove  —  rm,  271 

rename  —  mv,  219 

reverse  lines  in  —  rev,  268 

send  to  remote  host  —  uusend,  371 


file,  continued 

split  into  pieces  —  split,  308 
sum  —  sum  and  count  blocks  in  file,  315 
update  last  modified  date  of  —  touch,  351 
file  —  get  file  type,  133 
file  system 

cd  —  change  directory,  36 
check  and  repair  —  fsck,  508 
check  consistency  —  icheck,  518 
check  directory  —  dcheck,  497 
create  new  —  newfs,  548 
demount  —  umount,  539 
display  free  space,  104 
dump  information  —  dun^fs,  505 
free  space  display,  104 
make  —  mkfs,  533 
make  prototype —  mkproto,  535 
mount  —  mount,  539 
summarize  ownership  —  quot,  558 
tune  —  tunefs,  604 
unmount  —  umount,  539 
where  am  I  —  pwd,  253 
file  system  dump  —  dxuap,  503 
file  system  hierarchy  —  hi©r,  460 
file  system  restore  —  restore,  564 
file  transfer  protocol 
ftp  command,  144 

file  transfer  protocol  server  —  ftpd,  511 
filename  substitution 
in  C-Shell,  63  thru  65 

files 

basename  —  strip  affixes,  23 
cat  —  concatenate,  31 
ccat  —  compress  files,  53 
chmod  —  change  mode,  42 
emp  —  compare  files,  47 
colrm  —  remove  columns  from,  50 
comm —  find  commonality,  52 
compare,  47 

compare  three-way  differential,  107 
con^^ross  —  compress  files,  53 
convert  and  copy,  97 
copy,  54 

copy  standard  output  to  many  —  tee,  339 

cp  —  copy  files,  54 

cpio  —  copy  archives,  55 

crypt  —  encrypt/decrypt,  57 

decode,  57 

decrypt,  57 

determine  type  of,  133 
differential  compare,  105 
display  first  lines  of,  163 
display  names  —  Is,  196 
encode,  57 
encrypt,  57 
find,  134 

find  differences,  105 

prepare  files  for  printing  —  pr,  239 
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files,  continued 

search  for  patterns  in,  159 
sort  —  sort  or  merge  files,  303 
split  FORTRAN  file,  143 
three-way  differential  compare,  107 
transfer,  144 

uncon^ress  —  uncompress  files,  53 
filter 

reverse  paper  motions,  48 
find  —  find  files,  134 
find  lines  in  sorted  file  —  look,  187 
find  literature  references  —  refer,  267 
find  object  file  size  —  size,  300 
find  ordering  for  object  library  —  lordor,  189 
find  patterns  in  file,  159 

find  printable  strings  in  binary  file  —  strings, 
309 

find  program  —  whereis,  395 
fish  —  Go  Fish  game,  428 
flush  disk  activity  —  sync,  329 
fmt  —  simple  formatter,  136 
fold  —  fold  long  lines,  137 
font 

width  —  make  font  width  table,  388 
font  files 

convert  foreign  —  vswap,  386 
fonttool  —  font  editor,  138 
for  shell  command  —  sh,  292 
foreach  —  loop  on  list  of  names  —  csh,  67 
format  document  for  raster  printer  —  vtroff, 
387 

format  Lisp  programs  —  vlp,  382 
format  tables  —  tbl,  337 
FORTRAN 

f77  —  FORTRAN  compiler,  129 
print  file,  141 
split  file,  143 
FORTRAN  language 

rat  for  —  rational  FORTRAN,  260 
FORTRAN  programming  language 
ctags  —  create  tags  file,  78 
fortune  —  get  fortune,  429 
fpr  —  print  FORTRAN  file,  141 
from  —  who  is  mail  from,  142 
fsck  —  check  and  repair  file  system,  508 
fsirand  —  install  random  inode  generation 
numbers,  510 

fsplit  —  split  FORTRAN  file,  143 

ftp  —  file  transfer,  144 

ftpd  —  file  transfer  protocol  server,  511 

G 

gammontool  —  backgammon  game,  430 
gcoro  —  core  image  of  process,  147 
generate  adb  script  —  adbgen,  479 
generate  encryption  key  —  makekey,  532 


generate  lexical  analyzer  —  lex,  182 
generate  Pascal  execution  profile  —  pxp,  265 
generate  permuted  index  —  ptx,  252 
get  —  get  SCCS  file,  148 
get  magnetic  tape  unit  status  —  mt,  218,  218 
get  terminal  name  —  tty,  361 
get  terminal  options  —  stty,  311 
gettable  —  get  NIC  host  tables,  513 
getty  —  set  terminal  mode,  514 
gfxtool,  154 

glob  —  filename  expand  argument  list  —  csh, 

67 

goto  —  command  transfer  —  csh,  68 
gprof  —  call  graph  profile,  153 
graph  —  draw  graph,  157 
graphics 

spline  —  interpolate  smooth  curve,  307 
vplot  —  plot  on  Versatec,  383 
graphics  board  diagnostics  —  gxtest,  515 
graphics  filters  —  plot,  236 
graphics  tool,  154 
grep  —  pattern  scanner,  159 
group 

change,  41 

groups  —  display  group  membership,  162 
gxtest  —  graphics  board  diagnostics,  515 

H 

halt  —  stop  processor,  516 

halt  system  —  fasthalt,  507 

hangman  —  hangman  game,  432 

hashstat  —  display  hashing  statistics  —  csh, 

68 

head  —  display  head  of  file,  163 
help  —  get  SCCS  help,  164 
hexadecimal  dump  file  —  od,  224 
hier  —  file  system  hierarchy,  460 
history  —  display  history  list  —  csh,  68 
hostid  —  display  host  ID,  165 
hostname  —  display  host  name,  166 
htable  —  convert  NIC  standard  format  host 
tables,  517 

I 

i-node 

clear  —  clri,  487 
I/O  statistics  report  —  lostat,  524 
icheck  —  file  system  consistency  check,  518 
icontool,  167 

identify  file  version  —  what,  393 
if  shell  command  —  sh,  292 
if  —  conditional  statement  —  csh,  68 
ifconfig  —  configure  network  interface 
parameters,  519 

imemtest  —  memory  diagnostic,  520 
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incremental  file  system  dump  —  dump,  503 
incremental  file  system  restore  —  restore,  564 
indent  —  format  C  source,  170 
indexing 

ptx  —  generate  permuted  index,  252 
indxbib  —  make  inverted  index,  173 
inetd  —  internet  services  daemon,  521 
inews  —  submit  news  articles,  174 
information  handling 

awk  —  scan  and  process  patterns,  20 
be  —  calculator  language,  24 
inhibit  messages  —  mesg,  212 
in  it  —  process  control  initialization,  522 
initialize/diagnose  disk  —  diag,  498 
insert  literature  references  —  refer,  267 
install  —  install  files,  176 
install  yellow  pages  database  —  ypinit,  611 
interactive  graphics  drawing  —  bdraw,  426 
Internet  directory  service  —  whois,  399 
Internet  file  transfer  protocol  server  —  ftpd, 
511 

interpolate  smooth  curve  —  spline,  307 

interpret  Pascal  —  px,  254 

introduction  to  commands,  1 

introduction  to  miscellaneous  information,  457 

iostat  —  report  I/O  statistics,  524 

j 

jobs  —  display  job  list  —  esh,  68 
join  —  relational  database  operator,  177 

K 

kgmon  —  dump  profile  buffers,  526 

kill  —  terminate  process,  178 

kill  —  kill  jobs  and  processes  —  esh,  68 

L 

language 

vgrind  —  make  formatted  C  listings,  377 
languages 

cc  —  C  compiler,  33 
f77  —  FORTRAN  compiler,  129 
indent  —  format  C  source,  170 
lex  —  generate  lexical  analyzer,  182 
lint  —  C  program  verifier,  183 
nkstr  —  create  C  error  messages,  214 
pc  —  Pascal  compiler,  228,  233,  235 
pmerge  —  merge  Pascal  files,  237 
px  —  interpret  Pascal,  254 
pxp  —  generate  Pascal  execution  profile, 
255 

pxref  —  cross  reference  Pascal  program, 
257 

rat  for  —  rational  FORTRAN,  260 
tcov  —  code  coverage  tool,  338 
vlp  —  format  Lisp  programs,  382 


languages,  continued 

xstr  —  extract  strings  from  C  code,  403 
last  —  list  last  logins,  179 
lastcomm  —  display  last  commands,  180 
leave  —  remind  you  of  leaving  time,  181 
lex  —  generate  lexical  analyzer,  182 
library 

find  ordering  for  object  —  lorder,  189 
library  management 

ar  —  library  maintenance,  16 
ranlib  —  make  random  library,  258 
limit  —  alter  resource  limitations  —  esh,  69 
line  printer  control  —  Ipc,  526  thru  527 
line  printer  daemon  —  Ipd,  528 
lines 

find,  in  sorted  file  —  look,  187 
lines  in  file 

count  —  wc,  392 
lint  —  C  program  verifier,  183 
Lisp  programming  language 

vlp  —  format  Lisp  programs,  382 
literature  references 

find  and  insert  —  refer,  267 
load  frame  buffer  image  —  screenload,  286 
locate  program  —  whereis,  395 
lockscreen  —  save  window  context,  185 
login 

change  password  —  passwd,  227 
display  effective  user  name  —  vhoami,  398 
list  last  —  last,  179 
make  script  of  session  —  script,  288 
rwho  —  who  is  on  local  network,  278 
save  window  context  —  lockscreen,  185 
to  remote  machine  —  rlogln,  269 
what  are  users  doing  —  w,  389 
who  —  who  is  logged  in,  397 
login  accounting  —  ac,  478 
login  —  sign  on,  186,  296 
login  environment 

display  variables  —  printenv,  240 
tset  —  set  terminal  characteristics,  356 
tty  —  get  terminal  name,  361 
login  —  login  new  user  —  esh,  69 
logout  —  end  session  —  esh,  69 
look  —  find  lines  in  a  sorted  file,  187 
look  for  pattern  in  file,  159 
lookbib  —  find  bibliographic  references,  188 
lorder  —  find  ordering  for  object  library,  189 
Ipo  —  line  printer  control,  526 
Ipd  —  line  printer  daemon,  628 
Ipq  —  display  printer  queue,  190 
Ipr  —  print  files,  192 
Iprm  —  remove  print  jobs,  194 
Is  —  list  files,  196 
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M 

m4  —  macro  processor,  198 
macro  processor  —  in4,  198 
magnetic  tape 

backspace  files  —  mt,  218 
backspace  records  —  mt,  218 
erase  —  mt,  218 
forward  space  files  —  mt,  218 
forward  space  records  —  mt,  218 
get  unit  status  —  mt,  218 
manipulate  —  mt,  218 
place  unit  off-line  —  mt,  218 
retension  —  mt,  218 
rewind  —  mt,  218 
skip  backward  files  —  mt,  218 
skip  backward  records  —  mt,  218 
skip  forward  files  —  mt,  218 
skip  forward  records  —  mt,  218 
write  EOF  mark  on  —  mt,  218 
magnify  raster  image  —  rastropl,  259 
mail 

comsat  —  biff  server,  488 
enroll  for  secret  —  enroll,  402 
print  waiting  —  prmail,  241 
receive  secret  mail  —  enroll,  402 
send  secret  mail  —  xsend,  402 
mail  aliases 

create  database  —  newa liases,  547 
mail  —  send  and  receive  mail,  200 
mail  delivery  —  sendmail,  586 
mail  services 

biff  —  mail  notifier,  26 
binmail  —  version  7  mail,  27 
who  is  mail  from,  142 
mailaddr  —  mail  addressing,  464 
maintenance  and  operation,  475 
make 

delta,  99 
sees  delta,  99 
make  —  build  programs,  208 
make  directory  —  mkdir,  213 
make  file  system  —  mkfs,  533 
make  font  width  table  —  width,  388 
make  formatted  e  listings  —  vgrind,  377 
make  mail  aliases  database  —  newaliases, 
547 

make  new  file  system  —  newfs,  548 

make  permuted  index  —  ptx,  252 

make  prototype  file  system  —  mkproto,  535 

make  random  library  —  ranlib,  258 

make  script  of  terminal  session  —  script,  288 

make  special  file  —  mknod,  534 

make  system  configuration  files  —  con  fig,  489 

make  system  log  entry  —  syslog,  330 

make  system  special  files  —  makedev,  531 

make  yellow  pages  database  —  ypinit,  611 


make  yellow  pages  dbm  file  —  makedbm,  530 
makedbm  —  make  yellow  pages  dbm  file,  530 
makedev  —  make  system  special  files,  531 
makekey  —  generate  encryption  key,  532 
man  —  display  online  manuals,  211 
man  —  macros  to  format  manual  pages,  467 
manipulate  magnetic  tape  —  mt,  218 
manipulate  routing  tables  —  route,  573 
manual  pages  —  catman  —  create  cat  files  for, 
485 

describe  command  —  what  is,  394 
manuals 

display  online  —  man,  211 
me  —  macro  package,  469 
memory  diagnostic  —  imemtest,  520 
memory  diagnostics  —  sysdiag,  596 
merge  or  sort  files  —  sort,  303 
merge  Pascal  files  —  pmerge,  237 
mesg  —  permit  or  deny  messages,  212 
messages 

permit  or  deny  —  mesg,  212 
mille  —  Mille  Bornes  game,  433 
miscellaneous  information,  457 
mkdir  —  make  directory,  213 
mkfs  —  make  file  system,  533 
mknod  —  make  special  file,  534 
xnkproto  —  make  prototype  file  system,  535 
mkstr  —  create  C  error  messages,  214 
modes 

chmod  —  change  mode,  42 
monitor  program,  536 
monop  —  Monopoly  game,  436 
more  —  browse  text  file,  215 
mount  —  mount  file  system,  539 
mount  file  system  —  mount,  539 
mountd  —  NFS  mount  server,  541 
move  directory  —  mv,  219 
move  file  —  mv,  219 
move  print  jobs  —  Ipc,  526 
ms  —  macro  package,  471 
mt  —  manipulate  magnetic  tape,  218 
multiple  columns 

print  in  —  pr,  239 

mv  —  move  or  rename  files  or  directory,  219 

N 

ncheck  —  convert  i-numbers  to  filenames,  542 
nd  —  network  disk  control,  543 
neqn  —  mathematical  typesetting,  119 
netstat  —  display  network  status,  545 
network 

copy  files  across  —  rep,  261 
rwall  —  write  to  all  users,  277 
rwho  —  who  is  logged  in  on  local  network, 
278 
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network  debugging  —  ping,  552 
network  disk  control  —  nd,  543 
network  interface  parameters 
configure  —  ifconfig,  519 
network  news 

checknews  —  check  for  news,  39 
inews  —  submit  news  articles,  174 
read  articles  —  readnews,  262 
receive  unprocessed  articles  —  recnews, 
266 

submit  articles  —  post  news,  238 
network  routing  daemon  —  routed,  574 
network  rwall  server  —  rwalld,  580 
network  status 

display  —  netstat,  545 
newaliases  —  make  mail  aliases  database,  647 
newfs  —  make  new  file  system,  548 
newgrp  shell  command  —  sh,  296 
news 

checknews  —  check  for  news,  39 
read  articles  —  readnews,  262 
receive  unprocessed  articles  —  recnews, 
266 

submit  articles  —  postnews,  238 
news  articles 

receive  unprocessed,  562 
remove  outdated  —  expire,  506 
news  delivery  —  sendnews,  589 
NFS  mount  server  —  mountd,  541 
NFS  statistics 

display  —  nfsstat,  550 
nfsd  —  NFS  daemon,  549 
nfsstat  —  display  network  statistics,  550 
NIC  host  tables 

get  from  host  —  gettable,  513 
nice  —  change  priority  of  command,  220 
nice  —  run  low  priority  process  —  csh,  69 
nm  —  display  name  list,  221 
nohup  —  run  command  immune  to  hangup,  220 
nohup  —  run  command  immune  to  hangups  — 
csh,  69 

non-builtin  command  execution 
in  C-Shell,  75 

notify  —  request  immediate  notification  — 
csh,  69 
nroff 

checknr  —  check  nrofl/trofl  files,  40 
col  —  filter  reverse  paper  motions,  48 
colcrt  command,  49 
remove  constructs,  101 
nroff  —  document  formatter,  222 
number  —  convert  Arabic  numerals  to  English, 
438 


o 

object  code  management 

ar  library  maintenance,  16 
ranlib  —  make  random  library,  258 
object  file 

find  printable  strings  in  —  strings,  309 
size  —  find  object  file  size,  300 
strip  —  strip  symbols  and  relocation  bits, 
310 

object  library 

find  ordering  for  —  lorder,  189 
octal  dump  file  —  od,  224 
od  —  dump  file,  224 

onintr  —  handle  interrupts  in  scripts  —  csh, 
69 

online  manuals 

display  —  man,  211 
owner  of  file 

chown  —  change,  486 

p 

pac  —  printer/plotter  accounting,  551 
page  —  browse  text  file,  215 
page  size 

display  —  pages ize,  226 
pages ize  —  display  page  size,  226 
parser  generator  —  yacc,  404 
Pascal  compiler  —  pc,  228 
Pascal  interpreter  code  translator  —  pc,  233 
Pascal  language 

pmerge  —  merge  Pascal  files,  237 
px  —  interpret  Pascal,  254 
pxp  —  generate  Pascal  execution  profile, 
255 

pxref  —  cross  reference  Pascal  program, 
257 

Pascal  programming  language 
ctags  —  create  tags  file,  78 
Pascal  translator  and  interpreter  —  pc,  235 
passwd  —  change  login  password,  227 
password 

change  login  —  passwd,  227 
password  file 

edit  —  vipw,  608 
patterns 

search  in  file  for,  159 
pc  —  Pascal  compiler,  228 
per  f meter  —  display  performance  statistics, 

231 

perfmon  —  display  performance  statistics,  232 
performance  monitoring  —  per f meter,  231, 

232 

prof  —  display  program  profile,  242 
pxp  —  generate  Pascal  execution  profile, 
255 

time  —  time  command,  344 
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performance  tools 

display  call  graph  profile  data,  153 
peripheral  diagnostics  —  sysdiag,  596 
permissions 

chmod  —  change  mode,  42 
permit  messages  —  mesg,  212 
permuted  index 

generate  —  ptx,  252 

pi  —  Pascal  interpreter  code  translator,  233 

ping  —  debug  network,  552 

pix  —  Pascal  translator  and  interpreter,  235 

place  magnetic  tape  unit  off-line  —  mt,  218,  218 

plot  —  graphics  filters,  236 

plot  on  Versatec  —  vplot,  383 

pmerge  —  merge  Pascal  files,  237 

popd  —  pop  shell  directory  stack  —  csh,  70 

portmap  —  DARPA  to  RPC  mapper,  553 

postmortem  crash  analyzer  —  analyze,  483 

postnews  —  submit  news  articles,  238 

pr  —  prepare  files  for  printing,  239 

predefined  variables 

in  C-Shell,  72  thru  75 
prepare  files  for  printing  —  pr,  239 
pretty  print 

indent  —  format  C  source,  170 
pretty  printer 

vgrind  —  make  formatted  C  listings,  377 
vlp  —  format  Lisp  programs,  382 
preview  documents 

colcrt  command,  49 
print 

FORTRAN  file,  141 
print  files 

Ipr  —  print  files,  192 

print  values  from  YP  database  —  ypcat,  406 
print  waiting  mail  —  prmail,  241 
print  working  directory  name  —  pwd,  253 
printenv  —  display  environnment,  240 
printer 

abort  —  Ipc,  526 

clean  queue  —  Ipc,  526 

disable  queue  —  Ipc,  526 

Ipq  —  display  queue,  190 

enable  queue  —  Ipc,  526 

move  jobs  —  Ipc,  527 

remove  jobs  from  queue  —  Iprm,  194 

restart  —  Ipc,  526 

start  —  Ipc,  526 

status  of  —  Ipc,  526 

stop  —  Ipc,  526 

printer  control  —  Ipc,  526  thru  527 
printer  daemon  —  Ipd,  528 
printer /plotter  accounting,  551 
prmail  —  print  waiting  mall,  241 
process 

change  priority  —  renico,  563 


process,  continued 

display  status  —  ps,  247 
terminate  —  kill,  178 
wait  —  wait  process  completion,  390 
processes 

get  core  image  of,  147 
prof  —  display  program  profile,  242 
profile 

display  call  graph,  153 
profiling 

prof  —  display  program  profile,  242 
pxp  —  generate  Pascal  execution  profile, 
255 

programming  languages 

analyze  and  disperse  compiler  error  mes¬ 
sages,  121 
assembler,  18 
cc  —  C  compiler,  33 
f77  —  FORTRAN  compiler,  129 
lex  —  generate  lexical  analyzer,  182 
lint  —  C  program  verifier,  183 
pc  —  Pascal  compiler,  228,  233,  235 
pmerge  —  merge  Pascal  files,  237 
print  FORTRAN  file,  141 
px  —  interpret  Pascal,  254 
pxp  —  generate  Pascal  execution  profile, 
255 

pxref  —  cross  reference  Pascal  program, 
257 

split  FORTRAN  file,  143 
vgrind  —  make  formatted  C  listings,  377 
vlp  —  format  Lisp  programs,  382 
xstr  —  extract  strings  from  C  code,  403 
programming  tools 

adb  —  debug  tool,  2 
be  —  calculator  language,  24 
cb  —  C  beautifier,  32 
compiler  generator,  128 
ctags  —  create  tags  file,  78 
dbx  —  debugger,  80 
dbxtool  —  debugger,  90 
display  call  graph  profile  data,  153 
indent  —  format  C  source,  170 
install  —  install  files,  176 
lex  —  generate  lexical  analyzer,  182 
lint  —  C  program  verifier,  183 
lorder  —  find  ordering  for  object  library, 
189 

m4  —  macro  processor,  198 
maintain  object  libraries,  18 
make  —  build  programs,  208 
mkstr  —  create  C  error  messages,  214 
nm  —  display  name  list,  221 
prof  —  display  program  profile,  242 
ranlib  —  make  random  library,  258 
rat  for  —  rational  FORTRAN,  260 
sees  —  source  code  control,  280 
size  —  find  object  file  size,  300 
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programming  tools,  continued 

strings  —  find  printable  strings  in  binary 
file,  309 

strip  —  strip  symbols  and  relocation  bits, 
310 

tcov  —  code  coverage  tool,  338 
time  —  time  command,  344 
touch  —  update  last  modified  date  of  file, 
351 

yacc  —  compiler  generator,  404 
programs 

introduction,  1 

PROM  monitor  program,  536 

provide  truth  values  —  true,  355 

prs  —  display  SCCS  history,  243 

ps  —  display  process  status,  247 

pstat  —  display  system  statistics,  554 

ptx  —  generate  permuted  index,  252 

purge  directory  —  rmdir,  273 

purge  file  or  directory  —  rm,  271 

pushd  —  push  shell  directory  stack  —  csh,  70 

pwd  —  print  working  directory  name,  253 

px  —  interpret  Pascal,  254 

pxp  —  generate  Pascal  execution  profile,  255 

pxrof  —  cross  reference  Pascal  program,  257 

Q 

queue 

Ipq  —  display  printer,  190 
remove  jobs  from  printer  —  Iprm,  194 
quiz  —  test  knowledge,  439 
quot  —  summarize  file  system  ownership,  558 

R 

rain  —  display  raindrops,  440 
ranlib  —  make  random  library,  258 
rastrepl  —  magnify  raster  image,  259 
rat  for  —  rational  FORTRAN,  260 
rc  —  startup  commands,  559 
rep  —  remote  file  copy,  261 
rdate  —  remote  date,  560 
read  shell  command  —  sh,  296 
read  mail  —  mail,  200 
read  news  articles  —  readnews,  262 
readnevs  —  read  news  articles,  262 
readonly  shell  command  —  sh,  296 
reboot  —  system  startup  procedures,  561 
reboot  system  —  fastboot,  507 
rebuild  yellow  pages  database  —  ypmake,  612 
receive  secret  mail  —  enroll,  402 
receive  unprocessed  articles  —  recnews,  266 
receive  unprocessed  news  articles  —  recnews, 
562 

recnews  —  receive  unprocessed  articles,  266, 
562 


refer  —  insert  literature  references,  267 
rehash  —  recompute  command  hash  table  — 
csh,  70 

relational  database  operator  —  join,  177 
reminder  services 

biff  —  mail  notifier,  26 
calendar  —  reminder  service,  30 
leave  —  remind  you  of  leaving  time,  181 
remote  execution  server  —  rexecd,  567 
remote  file  copy  —  rep,  261 
remote  host 

send  file  to  —  uusend,  371 
remote  login  —  rlogin,  269 
remote  login  server  —  rlogind,  569 
remote  magtape  protocol  server  —  rmt,  571 
remote  shell  —  rsh,  274 
remote  shell  server  —  rshd,  577 
remote  system  cu 

connect  to  —  cu,  345 
remote  system  tip 

connect  to  —  tip,  346 
remove 

columns  from  file,  50 
delta  —  rmdel,  272 
filename  affixes,  23 

nroff,  troff,  tbi  and  eqn  constructs,  101 
remove  delta  from  SCCS  file  —  rmdel,  272 
remove  directory  —  rmdir,  273 
remove  outdated  news  articles  —  expire,  506 
remove  print  jobs  —  Iprm,  194 
remove  repeated  lines  —  uniq,  364 
rename  directory  —  mv,  219 
rename  file  —  mv,  219 
renice  —  change  process  priority,  563 
repeat  —  execute  command  repeatedly  — 
csh,  70 

reset  —  reset  terminal  bits,  358 

reset  terminal  bits  —  reset,  356 

restart  printer  —  Ipc,  526 

restore  —  restore  file  system,  564 

restore  file  system  —  restore,  564 

restore  frame  buffer  image  —  screenload,  286 

retension  magnetic  tape  —  mt,  218 

rev  —  reverse  lines  in  file,  268 

reverse  lines  in  file  —  rev,  268 

rewind  magnetic  tape  —  mt,  218 

rexecd  —  remote  execution  server,  567 

rlogin  —  remote  login,  269 

rlogind  —  remote  login  server,  569 

rmail  —  process  remote  mail,  570 

rmdel  —  remove  delta  from  SCCS  file,  272 

rmdir  —  remove  directory,  273 

rmt  —  remote  magtape  protocol  server,  571 

route  —  manipulate  routing  tables,  573 

routed  —  network  routing  daemon,  574 
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routing  tables 

manipulate  —  route,  573 
rpcinfo  —  report  RPC  information,  676 
rsh  —  remote  shell,  274 
rshd  —  remote  shell  server,  577 
rstatd  —  kernel  statistics  server,  579 
ruptime  —  display  status  of  local  hosts,  276 
rwalld  —  network  rwall  server,  580 
rwjio  —  who  is  logged  in  on  local  network,  278 
rwhod  —  system  status  server,  581 

s 

sa  —  accounting  summary,  583 
sail  —  wooden  ships  and  iron  men,  441 
savecore  —  save  OS  core  dump,  585 
sees  —  source  code  control  system,  280 
sees  commands 

admin  —  administer  SCCS,  12 
ede  —  change  delta  commentary,  37 
comb  —  combine  deltas,  51 
get  —  get  SCCS  file,  148 
help  —  get  SCCS  help,  164 
ede  —  display  SCCS  history,  243 
rmdel  —  remove  delta,  272 
sact  —  display  SCCS  file  editing  status, 
279 

scesdiff  —  compare  versions  of  SCCS 
file,  284 

unget  —  unget  SCCS  file,  363 
val  —  validate  SCCS  file,  373 
SCCS  delta 

change  commentary,  37 
combine,  51 
create,  99 

remove  —  rmdel,  272 
SCCS  history 
display,  243 

scesdiff  —  compare  versions  of  SCCS  file,  284 
screen  fonts 
edit,  138 

screen-oriented  editor  —  vi,  379 

screendump  —  dump  frame  buffer  image,  285 

screenload  —  restore  frame  buffer  image,  288 

script  —  make  script  of  terminal  session,  288 

search  for  files,  134 

search  for  pattern  in  file,  159 

secret  mail 

enroll  for  —  enroll,  402 
receive  —  enroll,  402 
send  —  xsend,  402 
sed  —  stream  editor,  289 
send  and  receive  mail  —  mail,  200 
send  file  to  remote  host  —  uusend,  371 
send  secret  mail  —  xsend,  402 
sendmail  —  mail  delivery  system,  586 
sendnews  —  news  delivery,  589 


servers 

biod  —  NFS  daemon,  549 
comsat  —  biff  server,  488 
ftpd  —  Internet  File  Transfer  Protocol,  511 
inetd  —  internet  services  daemon,  521 
mountd  —  mount  request  server,  541 
nfsd  —  NFS  daemon,  549 
rexecd  —  remote  execution  server,  567 
rlogind  —  remote  login  server,  569 
rshd  —  remote  shell  server,  577 
rstatd  —  kernel  statistics  server,  579 
rwalld  —  network  rwall  server,  580 
rwhod  —  system  status  server,  581 
tailed  —  talk  program  server,  599 
tolnetd  —  TELNET  protocol  server,  600 
tftpd  —  Trivial  File  Transfer  Protocol 
server,  601 

timed  —  DARPA  Time  server,  602 
yppasswdd  —  yellow  pages  password 
server,  613 
set 

current  domain,  108 
current  host  name,  166 
name  of  current  host,  166 
set  shell  command  —  sh,  296 
set  —  change  value  of  shell  variable  —  esh,  70 
set  terminal  characteristics  —  tset,  356 
set  terminal  options  —  stty,  311 
setenv  —  set  variable  in  environment  —  esh, 
70 

sh  —  Bourne  Shell,  292 
Shell 

Bourne  —  sh,  292 

shell 

change  login,  43 
chsh  —  change  shell,  43 
esh  —  C  shell,  58  thru  77 
remote  —  rsh,  274 
Shell  scripts 

sun  —  test  for  Sun  Workstation,  316 
true  —  provide  truth  values,  355 
vax  —  test  machine  is  VAX,  375 
shells 

false  command,  132 
shelltool,  297 

shift  shell  command  —  sh,  297 
shift  —  shift  argument  list  —  esh,  70 
sho%«nount  —  display  remote  mounts,  590 
shutdown  —  shut  down  system,  591 
login  —  sign  on,  186 

to  remote  machine  —  rlogin,  269 
signal  handling 
in  C-Shell,  76 
signon 

signon  last  —  last,  179 
size  —  find  object  file  size,  300 
skip  backward  magnetic  tape  files  —  mt,  218 
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skip  backward  magnetic  tape  records  —  mt,  218 
skip  forward  magnetic  tape  files  —  mt,  218 
skip  forward  magnetic  tape  records  —  mt,  218 
skyversion  —  display  SKY  version,  592 
sleep  —  suspend  execution,  301 
smoothing 

spline  —  interpolate  smooth  curve,  307 
snake  —  display  chase  game,  451 
soelim  —  eliminate  .so’s  from  nroff  input,  302 
sort  bibliographic  database  —  sortbib,  305 
sort  —  sort  or  merge  files,  303 
sort  or  merge  files  —  sort,  303 
sort  topologically  —  tsort,  360 
sortbib  —  sort  bibliographic  database,  305 
sorted  file 

find  lines  in  —  look,  187 
remove  repeated  lines  —  uniq,  364 
source  code  control  system  —  sees,  280 
source  —  read  commands  from  file  —  esh,  71 
spaces 

unexpand  to  tabs,  125 

special  characters  for  equations  —  eqnchar, 
459 

special  file 

make  —  mknod,  534 
special  files  —  makedev,  531 
spell  —  check  spelling,  306 
spellin  —  check  spelling,  306 
spellout  —  check  spelling,  306 
spline  —  interpolate  smooth  curve,  307 
split  —  split  file  into  pieces,  308 
stand-alone  utilities 

diag  —  initialize/diagnose  disk,  498 
gxtest  —  graphics  board  diagnostics,  515 
imemtest  —  memory  diagnostic,  520 
standard  output 

copy  to  many  files  —  tee,  339 
start  printer  —  Ipc,  526 
startup  procedures  —  reboot,  561 
statistics 

I/O  —  iostat,  524 
rstatd  —  kernel  statistics  server,  579 
statistics  of  NFS 

display  —  nfsstat,  550 
status  of  network 

display  —  netstat,  546 
status  of  printer  —  Ipc,  526 
sticky  —  set  sticky  bit,  593 
stop  printer  —  Ipc,  526 
stop  processor  —  halt,  516 
stop  —  halt  job  or  process  —  esh,  71 
stream  editor  —  sod,  289 
strings  —  find  printable  strings  in  binary  file, 
309 

strip 


strip,  continued 

filename  affixes,  23 

strip  —  strip  symbols  and  relocation  bits,  310 

stty  —  get  terminal  options,  311 

stty  —  set  terminal  options,  311 

su  —  substitute  user  id,  314 

submit  news  articles,  174,  238 

substitute  user  id  —  su,  314 

sum  —  sum  and  count  blocks  in  file,  315 

sun  —  test  for  Sun  Workstation,  316 

Sun  Workstation 

test  for  —  sun,  316 
suntools,  316 

suntools  —  Suntools  window  environment,  318 
SunWindows 

graphics  tool,  154 
icon  tool,  167 
shell  tool,  297 
start  up  environment,  316 
suspend  execution  —  sleep,  301 
suspend  —  suspend  shell  —  esh,  71 
swapon  —  specify  paging  device,  594 
switch  —  multi-way  branch  —  esh,  71 
sync  —  update  super  Mock,  329,  595 
sysdiag  —  system  diagnostics,  596 
syslog  —  make  system  log  entry,  330,  597 
system  administration 

adduser  —  add  new  user  account,  481 
analyze  —  crash  analyzer,  483 
catman  —  create  cat  files  for  manual,  485 
install  —  install  files,  176 
system  configuration  files 
build  —  config,  489 
system  maintenance  and  operation,  475 
system  PROM  monitor  program,  536 
system  special  files  —  makedev,  531 
system  status  server  —  rwhod,  581 

T 

tabs 

expand  to  spaces,  125 
tail  —  display  last  part  of  file,  331 
talk  —  talk  to  another  user,  332 
talkd  —  talk  server,  599 
tape 

backspace  files  —  mt,  218 
backspace  records  —  mt,  218 
erase  —  mt,  218 
forward  space  files  —  mt,  218 
forward  space  records  —  mt,  218 
get  unit  status  —  mt,  218 
manipulate  magnetic  —  mt,  218 
place  unit  off-line  —  mt,  218 
retension  —  mt,  218 
rewind  —  mt,  218 
skip  backward  files  —  mt,  218 
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tape,  continued 

skip  backward  records  —  mt,  218 
skip  forward  files  —  mt,  218 
skip  forward  records  —  mt,  218 
write  EOF  mark  on  —  mt,  218 
tape  archiver  —  tar,  333 
tar  —  tape  archiver,  333 
tbl 

remove  constructs,  101 
tbl  —  table  formatter,  337 
tcov  —  code  coverage  tool,  338 
tee  —  copy  standard  output  to  many  files,  339 
tektool  —  emulate  Tektronix  4014,  340 
Tektronix  4014 

emulate  —  tektool,  340 
telnet  —  TELNET  interface,  342 
telnetd  —  TELNET  protocol  server,  600 
terminal 

get  name  of  —  tty,  361 
get  options  —  stty,  311 
make  script  of  session  —  script,  288 
reset  bits  —  reset,  356 
set  characteristics  —  tset,  356 
set  options  —  stty,  311 
test  —  condition  command,  343 
test  for  Sun  Workstation  —  sun,  316 
test  machine  is  VAX  —  vax,  375 
text  editing 

ed  —  line  editor,  111 
edit  —  line  editor,  123 
ex  —  line  editor,  123 
sed  —  stream  editor,  289 
text  editor 

vi  —  visual  editor,  379 
text  file 

browse  through  —  more,  215 
browse  through  —  page,  215 
text  processing 

awk  —  scan  and  process  patterns,  20 
cat  —  concatenate  files,  31 
search  for  patterns,  159 
text  processing  utilities 

reverse  lines  in  file  —  rev,  268 
sort  —  sort  or  merge  files,  303 
spell  —  check  spelling,  306 
split  —  split  file  into  pieces,  308 
tail  —  display  last  part  of  file,  331 
tr  —  translate  characters,  352 
tsort  —  topological  sort,  360 
ul  —  underline  text,  362 
uniq  —  remove  repeated  lines,  364 
tftpd  —  Trivial  File  Transfer  Protocol  server, 
601 

time 

display  date  and,  79 
display  in  window,  46 
time  —  time  command,  344 


time  —  time  command  —  csh,  71 
timed  —  time  server,  602 
timed  event  services 

at  —  do  job  at  specified  time,  19 
calendar  —  reminder  service,  30 
leave  —  remind  you  of  leaving  time,  181 
timed  events  —  cron,  496 
times  shell  command  —  sh,  297 
tip  —  connect  to  remote  system,  346 
topological  sort  —  tsort,  360 
touch  —  update  last  modified  date  of  file,  351 
tr  —  translate  characters,  352 
translate  and  interpret  Pascal  programs  —  pc, 
235 

translate  characters  —  tr,  352 
transliterate  protocol  trace  —  trpt,  603 
trap  shell  command  —  sh,  297 
trek  —  Star  Trek  game,  452 
trof  f 

checknr  —  check  nroff/troff  files,  40 
col  —  filter  reverse  paper  motions,  48 
colcrt  command,  49 
remove  constructs,  101 
troff  —  typeset  documents,  353 
trpt  —  transliterate  protocol  trace,  603 
true  —  provide  truth  values,  355 
tset  —  set  terminal  characteristics,  356 
tsort  —  topological  sort,  360 
tty  —  get  terminal  name,  361 
tune  file  system  —  tunefs,  604 
tunefs  —  tune  file  system,  604 
typeset  documents  —  troff,  353 

u 

ul  —  underline  text,  362 
umask  shell  command  —  sh,  297 
umask  —  change/display  file  creation  mask  — 
csh,  71 

umount  —  unmount  file  system,  539 
unalias  —  remove  aliases  —  csh,  71 
uncon^ress  —  uncompress  files,  53 
uncompress  files,  53 
underline  text  —  ul,  362 
unexpand  —  spaces  to  tabs,  125 
unget  —  unget  SCCS  file,  363 
unhash  —  discard  hash  table  —  csh,  71 
uniq  —  remove  repeated  lines,  364 
units  —  convert  units,  365 
UNIX  to  UNIX  command  execution  —  uux,  372 
UNIX  to  UNIX  copy  —  uucp,  368 
unlimit  —  remove  resource  limitiations  — 
csh,  71 

unmount  file  system  —  umount,  539 
unset  —  discard  shell  variables  —  csh,  72 
unsetenv  —  remove  environment  variables  — 
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csh,  72 

update  —  update  super  block,  605 

update  last  modified  date  of  file  —  touch,  351 

update  super  block  —  sync,  329 

uptime  —  display  system  up  time,  366 

USENET 

checknews  —  check  for  news,  39 

user 

display  effective  name  —  whoami,  398 
talk  to  another  —  talk,  332 
write  to  another  —  write,  400 
user  id 

substitute  —  su,  314 
users 

list  last  logins  —  last,  179 
what  are  they  doing  —  w,  389 
who  —  who  is  logged  in,  397 
write  to  all  —  wall,  391 
users  —  display  users  on  system,  367 
utilities 

introduction,  1 

uuclean  —  clean  UUCP  spool  area,  606 
UUCP 

clean  spool  area  —  uuclean,  606 
UUCP  —  UNIX  to  UNIX  copy,  368 
UUCP  log  —  uulog,  368 
uudecode  —  decode  binary  file,  370 
uuencode  —  encode  binary  file,  370 
uulog  —  UUCP  log,  368 
uurec  —  receive  news  articles,  607 
uusend  —  send  file  to  remote  host,  371 
uux  —  UNIX  to  UNIX  command  execution,  372 

V 

val  —  validate  SCCS  file,  373 
validate  SCCS  file  —  val,  373 
variable  substitution 
in  C-Shell,  62  thru  63 
variables  in  C  Shell,  72  thru  75 
vax  —  test  machine  is  VAX,  375 
verification  tools 

lint  —  C  program  verifier,  183 
plot  graphics  on  —  vplot,  383 
version 

identify,  of  file  —  what,  393 
vfontlnfo  —  examine  font  files,  376 
vi  —  visual  editor,  379 
view  —  view  file,  381 
vlpw  —  edit  password  file,  608 
visual  editor  —  vi,  379 
vlp  —  format  Lisp  programs,  382 
vmstat  —  display  virtual  memory  statistics,  609 
vplot  —  plot  on  Versatec,  383 
vpq  —  display  raster  print  queue,  384 
vpr  —  print  on  raster  printer /plotter,  384 
vprint  —  print  on  raster  printer/plotter,  384 


vprm  —  remove  Jobs  from  raster  print  queue, 
384 

vswap  —  convert  foreign  font  files,  386 
vtroff  —  format  document  for  raster  printer, 
387 

width  —  make  font  width  table,  388 

w 

w  —  what  are  users  doing,  389 

wait  shell  command  —  sh,  297,  390 

wait  —  wait  for  background  process  —  csh,  72 

wall  —  write  to  all  users,  391 

wc  —  count  lines,  words,  characters  in  file,  392 

what  are  users  doing  —  w,  389 

what  —  identify  file  version,  393 

whatis  —  describe  command,  394 

wherels  —  find  program,  395 

which  —  find  program  file,  396 

while  shell  command  —  sh,  293 

while  —  repeat  commands  —  csh,  72 

who  —  who  is  logged  in,  397 

who  is  logged  in  on  local  network  —  rwho,  278 

whoami  —  display  effective  user  name,  398 

whois  —  Internet  directory  service,  399 

window 

save  context  —  lockscreen,  185 
window  environment  —  suntools,  318 
window  management 

adjacentscreens  command,  11 
words  in  file 

count  —  wc,  392 
working  directory 

cd  —  change  directory,  36 
display  name  of  —  pwd,  253 
worm  —  growing  worm  game,  453 
worms  —  animate  worms  on  display,  454 
write  —  write  to  another  user,  400 
write  EOF  mark  on  magnetic  tape  —  mt,  218 
write  to  all  users  —  wall,  391 
write  to  all  users  on  network  —  rwall,  277 
wunp  —  hunt  the  Wumpus  game,  455 

X 

xget  —  receive  secret  mail,  402 
xsend  —  send  secret  mail,  402 
xstr  —  extract  strings  from  C  code,  403 

Y 

yacc  —  compiler  generator,  404 
yellow  pages 

make  database  —  ypinit,  611 
make  dbm  file  —  makedbni,  530 
print  values  from  database  —  ypcat,  406 
rebuild  database  —  ypmake,  612 
yes  —  be  repetitively  affirmative,  405 
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ypcat  —  print  values  from  YP  database,  406 
ypinit  —  make  yellow  pages  database,  611 
ypmako  —  rebuild  yellow  pages  database,  612 
yppoll  —  yellow  pages  administration,  614 
yppull  —  yellow  pages  administration,  614 
yppush  —  yellow  pages  administration,  614 
ypserv  —  yellow  pages  server  process,  615 
ypwhich  —  who  is  yellow  pages  server,  617 
yppasswdd  —  yellow  pages  password  server, 
613 
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NICE(l) 


USER  COMMANDS 


NICE(l) 


NAME 

nice^  nohup  —  run  a  command  at  low  priority  only) 

SYNOPSIS 

nice  (  —number  [  command  [  arguments  | 
nohup  command  |  arguments  ] 

DESCRIPTION 

Nice  executes  command  with  low  scheduling  priority.  If  the  number  argument  is  present,  the 
priority  is  incremented  (higher  numbers  mean  lower  priorities)  by  that  amount  up  to  a  limit  of 
20.  The  default  number  is  10. 

The  super-user  may  run  commands  with  priority  higher  than  normal  by  using  a  negative  priority, 
e.g. 

Nohup  executes  command  immune  to  hangup  and  terminate  signals  from  the  controlling  termi¬ 
nal.  The  priority  is  incremented  by  5.  Nohup  should  be  invoked  from  the  shell  with  in  order 
to  prevent  it  from  responding  to  interrupts  by  or  stealing  the  input  from  the  next  person  who 
logs  in  on  the  same  terminal.  The  syntax  of  nice  is  also  different. 

FILES 

nohup.out  standard  output  and  standard  error  file  under  nohup 
SEE  ALSO 

csh(l),  nice(3C),  renice(8) 

DIAGNOSTICS 

Nice  returns  the  exit  status  of  the  subject  command. 

BUGS 

Nice  and  nohup  are  particular  to  aft(l).  If  you  use  ca/i(l),  then  commands  executed  with 
are  automatically  immune  to  hangup  signals  while  in  the  background.  There  is  a  builtin  com¬ 
mand  nohup  which  provides  immunity  from  terminate,  but  it  does  not  redirect  output  to 
nohup.out, 

Nice  is  built  into  caA(l)  with  a  slightly  different  syntax  than  described  here.  The  form  ‘^nice 
+10”  nices  to  positive  nice,  and  “nice  —10”  can  be  used  by  the  super-user  to  give  a  process  more 
of  the  processor. 
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